typescript-virtual-container 1.5.3 → 1.5.5

package/README.md

@@ -20,21 +20,9 @@
   - [Web shell (browser)](#web-shell-browser)
   - [Programmatic API](#programmatic-api)
 - [How It Works](#how-it-works)
-- [API Reference](#api-reference) *(open by default)*
-  - [`VirtualSshServer`](#virtualsshserver)
-  - [`VirtualSftpServer`](#virtualsftpserver)
-  - [`VirtualShell`](#virtualshell)
-  - [`VirtualFileSystem`](#virtualfilesystem)
-    - [Mount API](#mount-api)
-  - [`VirtualUserManager`](#virtualusermanager)
-  - [`VirtualPackageManager`](#virtualpackagemanager)
-  - [Snapshot Diff Tooling](#snapshot-diff-tooling)
-  - [`HoneyPot`](#honeypot)
-  - [`SshClient`](#sshclient-programmatic-api)
-  - [Key Types](#key-types)
-  - [Command Helpers](#command-helpers)
+- [API Reference](#api-reference)
 - [Examples](#examples)
-- [Built-in Commands (91)](#built-in-commands-91)
+- [Built-in Commands (106)](#built-in-commands-106)
 - [Shell Scripting](#shell-scripting)
 - [Linux Rootfs & VFS PATH Resolution](#linux-rootfs--vfs-path-resolution)
 - [Configuration](#configuration)
@@ -56,8 +44,8 @@
 | Mode | Entry point | Use case |
 |------|-------------|----------|
 | **SSH/SFTP server** | `VirtualSshServer` / `VirtualSftpServer` | Honeypots, remote testing, training environments |
-| **Web shell** | `builds/fortune-nyx-v1.5.3-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
-| **Standalone CLI** | `builds/fortune-nyx-v1.5.3-directbash-k6.1.0.mjs` (single file) | Local shell, one-liner demos, no install required |
+| **Web shell** | `builds/fortune-nyx-v1.5.5-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
+| **Standalone CLI** | `builds/fortune-nyx-v1.5.5-directbash-k6.1.0.mjs` (single file) | Local shell, one-liner demos, no install required |
 <!-- /BUILD:mode-table -->
 
 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.
@@ -78,17 +66,17 @@ npm install typescript-virtual-container
 <!-- BUILD:curl-start -->
 #### Interactivea local shell — persists VFS in .vfs/ in the current directory
 ```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.3-directbash-k6.1.0.mjs -o fortune-nyx-v1.5.3-directbash-k6.1.0.mjs && node fortune-nyx-v1.5.3-directbash-k6.1.0.mjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.5-directbash-k6.1.0.mjs -o fortune-nyx-v1.5.5-directbash-k6.1.0.mjs && node fortune-nyx-v1.5.5-directbash-k6.1.0.mjs
 ```
 
 #### SSH server (connect with any SSH client on port 2222)
 ```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.3-ssh.cjs -o fortune-nyx-v1.5.3-ssh.cjs && node fortune-nyx-v1.5.3-ssh.cjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.5-ssh.cjs -o fortune-nyx-v1.5.5-ssh.cjs && node fortune-nyx-v1.5.5-ssh.cjs
 ```
 
 #### SSH server without SFTP (lighter build)
 ```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.3-ssh-nosftp.js -o fortune-nyx-v1.5.3-ssh-nosftp.js && node fortune-nyx-v1.5.3-ssh-nosftp.js
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.5-ssh-nosftp.js -o fortune-nyx-v1.5.5-ssh-nosftp.js && node fortune-nyx-v1.5.5-ssh-nosftp.js
 ```
 <!-- /BUILD:curl-start -->
 
@@ -96,13 +84,13 @@ curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-cont
 > The standalone builds are intended for quick demos and testing. For production use, it's recommended to install the package and import the relevant classes directly in your codebase for better performance, stability, and security.
 
 <!-- BUILD:selfStandalone-options -->
-**`fortune-nyx-v1.5.3-directbash-k6.1.0.mjs` options:**
+**`fortune-nyx-v1.5.5-directbash-k6.1.0.mjs` options:**
 
 ```bash
-node fortune-nyx-v1.5.3-directbash-k6.1.0.mjs                  # boot as root
-node fortune-nyx-v1.5.3-directbash-k6.1.0.mjs --user alice     # boot as alice (prompts for password if set)
-node fortune-nyx-v1.5.3-directbash-k6.1.0.mjs --user=alice     # same, inline form
-SSH_MIMIC_HOSTNAME=my-box node fortune-nyx-v1.5.3-directbash-k6.1.0.mjs  # custom hostname
+node fortune-nyx-v1.5.5-directbash-k6.1.0.mjs                  # boot as root
+node fortune-nyx-v1.5.5-directbash-k6.1.0.mjs --user alice     # boot as alice (prompts for password if set)
+node fortune-nyx-v1.5.5-directbash-k6.1.0.mjs --user=alice     # same, inline form
+SSH_MIMIC_HOSTNAME=my-box node fortune-nyx-v1.5.5-directbash-k6.1.0.mjs  # custom hostname
 ```
 <!-- /BUILD:selfStandalone-options -->
 
@@ -129,7 +117,7 @@ Two browser bundles are available:
 <!-- BUILD:web-table -->
 | Bundle | Format | Entry point | Use case |
 |--------|--------|-------------|----------|
-| `builds/fortune-nyx-v1.5.3-web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
+| `builds/fortune-nyx-v1.5.5-web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
 <!-- /BUILD:web-table -->
 
 Both bundles persist the VFS in **IndexedDB** — state survives page reloads.
@@ -141,11 +129,11 @@ bun run build-all       # rebuild everything
 ```
 
 <!-- BUILD:web-options -->
-**`fortune-nyx-v1.5.3-web.min.js`** — lightweight shell with IndexedDB VFS:
+**`fortune-nyx-v1.5.5-web.min.js`** — lightweight shell with IndexedDB VFS:
 
 ```html
 <script type="module">
-  import { createWebShell } from "./builds/fortune-nyx-v1.5.3-web.min.js";
+  import { createWebShell } from "./builds/fortune-nyx-v1.5.5-web.min.js";
 
   const shell = createWebShell("web-vm", {
     vfs: { databaseName: "virtual-env-js", storeName: "vfs" },
@@ -157,11 +145,11 @@ bun run build-all       # rebuild everything
 </script>
 ```
 
-**`fortune-nyx-v1.5.3-web.min.js`** — mirrors the `VirtualShell` programmatic API:
+**`fortune-nyx-v1.5.5-web.min.js`** — mirrors the `VirtualShell` programmatic API:
 
 ```html
 <script type="module">
-  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.5.3-web.min.js";
+  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.5.5-web.min.js";
 
   const shell = createVirtualShellShim("web-vm");
   await shell.ensureInitialized();
@@ -242,502 +230,6 @@ console.log(r.stdout);
 <!-- https://itsrealfortune.fr/typescript-virtual-container/ -->
 API reference for all core classes and utilities. Designed for quick lookup while developing with the library. More extensive documentation, examples, and guides are available in <a href="https://itsrealfortune.fr/typescript-virtual-container/">the documentation</a>.
 
-### `VirtualSshServer`
-
-```typescript
-new VirtualSshServer({
-  port: number;
-  hostname?: string;          // default: "typescript-vm"
-  shell?: VirtualShell;       // share state with SFTP server
-  maxAuthAttempts?: number;   // default: 5
-  lockoutDurationMs?: number; // default: 60_000
-})
-```
-
-If `shell` is omitted, the server creates `new VirtualShell(hostname)` internally.
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `start(): Promise<number>` | Initialize VFS, users, start listening. Returns bound port. |
-| `stop(): void` | Gracefully close server and all active connections. |
-| `clearLockout(ip): void` | Manually lift a rate-limit lockout for an IP. |
-| `getVfs(): VirtualFileSystem \| null` | Access VFS instance (null before start). |
-| `getUsers(): VirtualUserManager \| null` | Access user manager (null before start). |
-| `getHostname(): string` | Returns configured hostname. |
-
-**Events**
-
-| Event | Data | Description |
-|-------|------|-------------|
-| `start` | `{ port }` | Server started |
-| `stop` | — | Server stopped |
-| `auth:success` | `{ username, remoteAddress, method? }` | Authenticated |
-| `auth:failure` | `{ username, remoteAddress, reason?, method? }` | Auth failed |
-| `auth:lockout` | `{ ip, until: Date }` | IP locked out |
-| `client:connect` | — | New SSH client connected |
-| `client:disconnect` | `{ user }` | SSH client disconnected |
-
----
-
-### `VirtualSftpServer`
-
-```typescript
-new VirtualSftpServer({
-  port: number;
-  hostname?: string;
-  shell?: VirtualShell;        // share state with SSH server (recommended)
-  vfs?: VirtualFileSystem;     // explicit if no shell
-  users?: VirtualUserManager;  // explicit if no shell
-})
-```
-
-Supports `password` and `keyboard-interactive` auth. Confines all operations to `/home/<user>`. Unsupported operations return `OP_UNSUPPORTED`.
-
-**Methods:** `start(): Promise<number>`, `stop(): void`
-
-**Events:** `start`, `stop`, `auth:success { username, remoteAddress }`, `auth:failure { username, remoteAddress }`, `client:connect`, `client:disconnect { user }`
-
----
-
-### `VirtualShell`
-
-Coordinates the VFS, user manager, package manager, and command runtime.
-
-```typescript
-new VirtualShell(
-  hostname: string,
-  properties?: ShellProperties,   // kernel, os, arch — surfaced by uname/neofetch
-  vfsOptions?: VfsOptions,        // { mode: "memory"|"fs", snapshotPath?: string }
-)
-```
-
-```typescript
-interface ShellProperties {
-  kernel: string;  // e.g. "1.0.0+itsrealfortune+1-amd64"
-  os: string;      // e.g. "Fortune GNU/Linux x64"
-  arch: string;    // e.g. "x86_64"
-}
-```
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `ensureInitialized(): Promise<void>` | Await before using programmatically. |
-| `addCommand(name, params, callback)` | Register a custom shell command. |
-| `executeCommand(rawInput, authUser, cwd)` | Run a raw command string. |
-| `startInteractiveSession(stream, authUser, sessionId, remoteAddress, terminalSize)` | Attach a PTY session. |
-| `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. |
-| `getHostname(): string` | Returns configured hostname. |
-
-**Public fields**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `vfs` | `VirtualFileSystem` | Backing virtual filesystem. |
-| `users` | `VirtualUserManager` | Virtual user database. |
-| `packageManager` | `VirtualPackageManager` | APT/dpkg package manager. |
-| `hostname` | `string` | Hostname shown in prompt and SSH ident. |
-| `properties` | `ShellProperties` | Distro identity strings. |
-| `startTime` | `number` | Unix ms timestamp of shell creation. |
-
-**Events:** `initialized`, `command { command, user, cwd }`, `session:start { user, sessionId, remoteAddress }`
-
-**Custom command example:**
-
-```typescript
-shell.addCommand("greet", ["[name]"], ({ args, authUser }) => {
-  const name = args[0] ?? authUser;
-  return { stdout: `Hello, ${name}!\n`, exitCode: 0 };
-});
-```
-
----
-
-### `VirtualFileSystem`
-
-Pure in-memory virtual filesystem. No host filesystem access at runtime.
-
-```typescript
-// Memory mode (default) — ephemeral
-new VirtualFileSystem()
-
-// FS mode — persists to binary .vfsb file
-new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" })
-await vfs.restoreMirror(); // load from disk (no-op if no file yet)
-await vfs.flushMirror();   // save to disk
-```
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `mkdir(path, mode?)` | Create directory and any missing parents. |
-| `writeFile(path, content, options?)` | Write file. `options.compress` gzips; `options.mode` sets POSIX mode bits. |
-| `readFile(path): string` | Read as UTF-8. Transparently decompresses gzip. |
-| `readFileRaw(path): Buffer` | Read as Buffer. |
-| `exists(path): boolean` | Test existence. |
-| `stat(path): VfsNodeStats` | Returns metadata. |
-| `list(path?): string[]` | List direct children (sorted). |
-| `tree(path?): string` | Render ASCII directory tree. |
-| `move(from, to)` | Move or rename. |
-| `remove(path, options?)` | Delete. `options.recursive` required for non-empty dirs. |
-| `chmod(path, mode)` | Update POSIX mode bits. |
-| `compressFile(path)` / `decompressFile(path)` | Gzip-compress / gunzip in place. |
-| `symlink(target, linkPath)` | Create symbolic link. |
-| `isSymlink(path): boolean` | Test if path is a symlink. |
-| `resolveSymlink(path, maxDepth?): string` | Resolve symlink chain (default max 8 hops). |
-| `getUsageBytes(path?): number` | Total stored bytes under a path. |
-| `toSnapshot(): VfsSnapshot` | Export tree as JSON-serialisable snapshot. |
-| `importSnapshot(snapshot)` | Replace current state from a snapshot. |
-| `restoreMirror(): Promise<void>` | Load from disk (`"fs"` mode) / no-op otherwise. |
-| `flushMirror(): Promise<void>` | Save to disk (`"fs"` mode) / emit event otherwise. |
-| `VirtualFileSystem.fromSnapshot(snapshot)` | **Static.** Create memory-mode instance from snapshot. |
-
-**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`).
-
-| Metric | JSON+base64 | VFSB binary |
-|--------|-------------|-------------|
-| File size (10 MB content) | ~13.7 MB | ~10.0 MB |
-| Encode time | ~12 ms | ~0.04 ms |
-| Decode time | ~18 ms | ~0.07 ms |
-
-Wire format: 5-byte header (`VFS!` magic + version), followed by a recursive node tree with type, name, mode, timestamps, and raw content bytes (no base64). Legacy JSON snapshots are auto-detected and migrated on first `flushMirror()`.
-
-Low-level API:
-```typescript
-import { encodeVfs, decodeVfs, isBinarySnapshot } from "typescript-virtual-container/src/VirtualFileSystem/binaryPack";
-const buf  = encodeVfs(vfs.root);
-const root = decodeVfs(buf);
-isBinarySnapshot(buf); // true — starts with "VFS!" magic
-```
-
----
-
-### `VirtualUserManager`
-
-Manages users, password hashing (scrypt), sudo privileges, storage quotas, SSH public keys, and session tracking.
-
-```typescript
-new VirtualUserManager(
-  vfs: VirtualFileSystem,
-  autoSudoForNewUsers?: boolean, // default: true
-)
-```
-
-Auth data is stored at `/etc/` inside the VFS.
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `initialize(): Promise<void>` | Load users/sudoers, ensure root exists. |
-| `verifyPassword(username, password): boolean` | Check plaintext password. |
-| `hasPassword(username): boolean` | Returns `true` if a password is set. |
-| `hashPassword(password): string` | Hash with scrypt (or SHA-256 with `SSH_MIMIC_FAST_PASSWORD_HASH=1`). |
-| `getPasswordHash(username): string \| null` | Raw stored hash. |
-| `addUser(username, password): Promise<void>` | Create user with home directory. |
-| `deleteUser(username): Promise<void>` | Delete user. Throws on `root` or missing user. |
-| `setPassword(username, password): Promise<void>` | Update password. |
-| `isSudoer(username): boolean` | Returns `true` if user has sudo. |
-| `addSudoer(username): Promise<void>` | Grant sudo. |
-| `removeSudoer(username): Promise<void>` | Revoke sudo. Throws on `root`. |
-| `setQuotaBytes(username, maxBytes): Promise<void>` | Set per-user write quota. |
-| `clearQuota(username): Promise<void>` | Remove quota limit. |
-| `getQuotaBytes(username): number \| null` | Quota in bytes, or `null` if unlimited. |
-| `getUsageBytes(username): number` | Current usage under `/home/<user>`. |
-| `assertWriteWithinQuota(username, path, content)` | Throws if write would exceed quota. |
-| `listUsers(): string[]` | Sorted list of all usernames. |
-| `addAuthorizedKey(username, algo, data)` | Register SSH public key. |
-| `getAuthorizedKeys(username)` | List authorized keys. |
-| `removeAuthorizedKeys(username)` | Revoke all authorized keys. |
-| `registerSession(username, remoteAddress): VirtualActiveSession` | Allocate virtual TTY and register session. |
-| `unregisterSession(sessionId): void` | Remove session on disconnect. Safe with `null`. |
-| `updateSession(sessionId, username, remoteAddress): void` | Update after `su`/`sudo` identity change. |
-| `listActiveSessions(): VirtualActiveSession[]` | All active sessions sorted by start time. |
-
-**Events:** `initialized`, `user:add { username }`, `user:delete { username }`, `key:add { username, algo }`, `key:remove { username }`, `session:register { sessionId, username, remoteAddress }`, `session:unregister { sessionId, username }`
-
----
-
-### `VirtualPackageManager`
-
-Simulates APT/dpkg backed by a 25-package registry. Accessed via `shell.packageManager`.
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `install(names, opts?)` | Install packages (resolves deps, writes files to VFS). Returns `{ output, exitCode }` |
-| `remove(names, opts?)` | Remove. `opts.purge` also removes config files. |
-| `search(term)` | Search by name or description. |
-| `show(name)` | dpkg-style metadata block. |
-| `listInstalled()` | All installed packages as `InstalledPackage[]`. |
-| `listAvailable()` | All registry packages. |
-| `isInstalled(name)` | Returns `true` if installed. |
-| `installedCount()` | Count of installed packages. |
-| `findInRegistry(name)` | Look up `PackageDefinition` by name. |
-
-**Custom packages:**
-
-```typescript
-const customPkg = {
-  name: "myapp",
-  version: "1.0.0",
-  description: "My application",
-  files: [
-    { path: "/usr/bin/myapp", content: "#!/bin/sh\necho myapp v1.0.0\n", mode: 0o755 },
-    { path: "/etc/myapp/config.json", content: JSON.stringify({ port: 3000 }) },
-  ],
-  onInstall: (vfs) => {
-    vfs.mkdir("/var/lib/myapp", 0o755);
-    vfs.mkdir("/var/log/myapp", 0o755);
-  },
-};
-```
-
----
-
-### Snapshot Diff Tooling
-
-```typescript
-import { diffSnapshots, formatDiff, assertDiff } from "typescript-virtual-container";
-```
-
-**`diffSnapshots(before, after, options?): VfsDiff`**
-
-```typescript
-const before = shell.vfs.toSnapshot();
-await client.exec("apt install vim && mkdir -p /app");
-const after = shell.vfs.toSnapshot();
-
-const diff = diffSnapshots(before, after, { ignore: ["/proc", "/var/log"] });
-diff.clean;     // false
-diff.added;     // [{ path: "/usr/bin/vim", type: "file" }, ...]
-diff.modified;  // [{ path: "/var/lib/dpkg/status", before: "...", after: "..." }]
-```
-
-**`formatDiff(diff, options?): string`** — human-readable output like `git diff --stat`. Options: `showContent: boolean`, `maxContentChars: number`.
-
-**`assertDiff(diff, expected): void`** — throws on mismatch, designed for test suites:
-
-```typescript
-assertDiff(diff, { added: ["/app", "/usr/bin/vim"], modified: ["/var/lib/dpkg/status"] });
-```
-
----
-
-### `HoneyPot`
-
-Comprehensive security auditing. Attaches to all core components to log activity and detect anomalies.
-
-```typescript
-new HoneyPot(maxLogSize?: number) // default: 10000
-```
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `attach(shell, vfs, users, ssh?, sftp?)` | Subscribe to all event sources. |
-| `getAuditLog(type?, source?): AuditLogEntry[]` | Full log, optionally filtered. |
-| `getStats(): Readonly<HoneyPotStats>` | Aggregated activity counters. |
-| `getRecent(limit?): AuditLogEntry[]` | Most recent entries, reverse-chronological. |
-| `detectAnomalies()` | Returns `{ type, severity, message }[]`. |
-| `reset()` | Clear log and reset counters. |
-| `exportJson(): string` | Serialise full log + stats to JSON. |
-
-`detectAnomalies` detects: high auth failure rates, excessive failures, unusual command volume, unusual file write volume.
-
-```typescript
-const hp = new HoneyPot(50_000);
-hp.attach(shell, shell.vfs, shell.users, ssh);
-
-hp.getAuditLog("auth:failure").forEach(e =>
-  console.log(e.details.username, e.details.remoteAddress)
-);
-
-hp.detectAnomalies().forEach(a =>
-  console.log(`[${a.severity.toUpperCase()}] ${a.type}: ${a.message}`)
-);
-
-process.on("SIGINT", () => {
-  require("fs").writeFileSync("audit.json", hp.exportJson());
-  process.exit(0);
-});
-```
-
----
-
-### `SshClient` (Programmatic API)
-
-Execute shell commands against a `VirtualShell` without SSH overhead. Maintains working-directory state.
-
-```typescript
-new SshClient(shell: VirtualShell, username: string)
-```
-
-**Methods**
-
-| Method | Description |
-|--------|-------------|
-| `exec(command): Promise<CommandResult>` | Run raw command string (supports `&&`, `\|`, etc.). |
-| `ls(path?)` | List directory. |
-| `pwd()` | Print current working directory. |
-| `cd(path)` | Change directory. Updates internal cwd on success. |
-| `cat(path)` | Read file via `cat` command. |
-| `readFile(path)` | Read file directly from VFS. |
-| `writeFile(path, content)` | Write file directly to VFS. |
-| `mkdir(path, recursive?)` | Create directory. |
-| `touch(path)` | Create empty file. |
-| `rm(path, recursive?)` | Remove file or directory. |
-| `tree(path?)` | Render ASCII directory tree. |
-| `whoami()` / `hostname()` / `who()` | System info commands. |
-| `getCwd(): string` | Returns current cwd (no I/O). |
-| `getUsername(): string` | Returns authenticated username. |
-
----
-
-### Key Types
-
-```typescript
-interface CommandResult {
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number;
-  nextCwd?: string;
-  clearScreen?: boolean;
-  closeSession?: boolean;
-  switchUser?: string;
-  openEditor?: NanoEditorSession;
-  openHtop?: boolean;
-  sudoChallenge?: SudoChallenge;
-}
-
-interface ShellEnv {
-  vars: Record<string, string>; // $VAR accessible in expansions
-  lastExitCode: number;         // $?
-}
-
-interface ShellModule {
-  name: string;
-  params: string[];
-  aliases?: string[];
-  description?: string;
-  category?: string; // navigation|files|text|archive|system|package|network|shell|users|misc
-  run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>;
-}
-
-interface CommandContext {
-  authUser: string;
-  hostname: string;
-  activeSessions: VirtualActiveSession[];
-  rawInput: string;
-  mode: "shell" | "exec";
-  args: string[];
-  stdin?: string;
-  cwd: string;
-  shell: VirtualShell;
-  env: ShellEnv;
-}
-
-interface VirtualActiveSession {
-  id: string;
-  username: string;
-  tty: string;
-  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
-}
-```
-
----
-
-### Command Helpers
-
-```typescript
-import { ifFlag, getFlag, getArg, parseArgs } from "typescript-virtual-container";
-
-// ifFlag — true if any given flag appears in args
-ifFlag(args, ["-r", "--recursive"]) // boolean
-
-// getFlag — value, true if valueless, undefined if absent
-getFlag(args, ["-o", "--output"])
-// ["--output", "file.txt"] → "file.txt"
-// ["--output=file.txt"]    → "file.txt"
-// ["--verbose"]            → true
-// []                       → undefined
-
-// getArg — positional at index N, skipping known flags
-// args = ["-r", "src", "dest"]
-getArg(args, 0, { flags: ["-r"] }) // "src"
-getArg(args, 1, { flags: ["-r"] }) // "dest"
-
-// parseArgs — structured parse
-const { flags, flagsWithValues, positionals } = parseArgs(args, {
-  flags:          ["-r", "--recursive"],
-  flagsWithValue: ["-o", "--output"],
-});
-```
-
 </details>
 
 ---
@@ -983,9 +475,9 @@ echo "Welcome back, root!"
 ---
 
 <details>
-<summary><strong>Built-in Commands (91)</strong></summary>
+<summary><strong>Built-in Commands (106)</strong></summary>
 
-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.
+Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage. Type `man <command>` for full manual pages — all 106 commands are documented.
 
 ### Navigation
 
@@ -1029,6 +521,9 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `tee [files]` | `-a` | Read stdin, write to stdout and files |
 | `tr <set1> [set2]` | `-d` | Translate or delete characters |
 | `uniq` | `-c` `-d` `-u` | Filter repeated lines |
+| `basename <path> [suffix]` | `-a` `-s` | Strip directory and suffix from path |
+| `dirname <path>` | | Strip last component from path |
+| `file <path...>` | | Determine file type (magic bytes) |
 | `wc [files]` | `-l` `-w` `-c` | Word/line/byte count |
 | `xargs [cmd]` | | Build and execute commands from stdin |
 
@@ -1051,7 +546,10 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `hostname` | | Print hostname |
 | `htop` | | System monitor (mock) |
 | `id [user]` | | User identity (uid/gid/groups) |
+| `dmesg` | `-n` | Print kernel ring buffer messages |
+| `ip <object>` | `addr` `route` `link` `neigh` | Modern network interface/routing tool |
 | `kill [-9] <pid>` | | Send signal (mock) |
+| `last [user]` | | Show login history |
 | `lsb_release` | `-a` `-i` `-d` `-r` `-c` | Distribution info |
 | `neofetch` | | System info (real package count and uptime) |
 | `node` | `--version` `-e` `-p` | Virtual JS runtime; **requires `apt install nodejs`** |
@@ -1063,6 +561,7 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `sleep <seconds>` | | Delay execution |
 | `uname` | `-a` `-r` `-m` | System information |
 | `uptime` | `-p` `-s` | Running time |
+| `w` | | Who is logged on and what they are doing |
 | `who` | | Active sessions |
 | `whoami` | | Current user |
 
@@ -1097,12 +596,25 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `source <file>` | | Execute file in current env; alias `.` |
 | `test <expr>` / `[ <expr> ]` | | POSIX conditional: `-f` `-d` `-e` `-z` `-n` `-x` `-s` `=` `!=` `-eq` `-lt` `-gt` `-le` `-ge` `!` `-a` `-o` |
 | `trap [action] [signal]` | | Signal handlers; supports `EXIT` |
+| `stty` | `-a` `size` | Print/change terminal line settings |
+| `tput <cap>` | `cols` `lines` `setaf` `bold` `sgr0` | Query terminfo / output terminal escape sequences |
 | `true` | | Return exit code 0 |
 | `type <command>` | | Describe command interpretation |
 | `unalias <name>` | `-a` | Remove aliases |
 | `unset <VAR>` | | Remove shell variable |
 | `which <command>` | | Locate command in `$PATH` |
 
+### Misc & Fun
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `cmatrix` | | Matrix-style falling characters |
+| `cowsay [msg]` | | ASCII cow saying something |
+| `cowthink [msg]` | | ASCII cow thinking |
+| `fortune` | | Print a random adage |
+| `sl` | | Steam locomotive (cure for mistyping `ls`) |
+| `yes [string]` | | Repeatedly output string until killed |
+
 ### Package Management
 
 | Command | Flags | Description |
@@ -1123,7 +635,7 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `su [user]` | | Switch user |
 | `sudo <cmd>` | `-i` | Run as root |
 
-**ℹ️ All 91 built-in commands include complete JSDoc documentation** with `@category` and `@params` tags. See [src/commands/](https://github.com/itsrealfortune/typescript-virtual-container/tree/main/src/commands) for source code and inline documentation.
+**ℹ️ All 106 built-in commands include complete JSDoc documentation** with `@category` and `@params` tags. See [src/commands/](https://github.com/itsrealfortune/typescript-virtual-container/tree/main/src/commands) for source code and inline documentation.
 
 Custom commands: `shell.addCommand(name, params, callback)`.
 
@@ -1646,15 +1158,15 @@ 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] 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] 106 built-in commands across 10 categories (added `w`, `ip`, `dmesg`, `last`, `basename`, `dirname`, `file`, `tput`, `stty`, `yes`, `fortune`, `cowsay`, `cowthink`, `cmatrix`, `sl`)
+- [x] Real shell interpreter — `if`/`for`/`while`/`case`/functions, `$(cmd)`, `$((expr))`, `${#VAR}`, `{a,b,c}` brace expansion, `{1..N}` ranges, `*.glob` expansion, `!!`/`!n` history expansion, `\` line continuation, `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
 <!-- BUILD:changelog -->
-- [x] Web shell bundles (`fortune-nyx-v1.5.3-web.min.js`) — fully browser-native with IndexedDB VFS
-- [x] Self-standalone CLI (`fortune-nyx-v1.5.3-directbash-k6.1.0.mjs`) — single-file interactive shell, per-user history, tab completion
+- [x] Web shell bundles (`fortune-nyx-v1.5.5-web.min.js`) — fully browser-native with IndexedDB VFS
+- [x] Self-standalone CLI (`fortune-nyx-v1.5.5-directbash-k6.1.0.mjs`) — single-file interactive shell, per-user history, tab completion
 <!-- /BUILD:changelog -->
 - [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)