typescript-virtual-container 1.5.4 → 1.5.6

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 (106)](#built-in-commands-106)
+- [Built-in Commands (118)](#built-in-commands-118)
 - [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.4-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
-| **Standalone CLI** | `builds/fortune-nyx-v1.5.4-directbash-k6.1.0.mjs` (single file) | Local shell, one-liner demos, no install required |
+| **Web shell** | `builds/fortune-nyx-v1.5.6-web.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
+| **Standalone CLI** | `builds/fortune-nyx-v1.5.6-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.4-directbash-k6.1.0.mjs -o fortune-nyx-v1.5.4-directbash-k6.1.0.mjs && node fortune-nyx-v1.5.4-directbash-k6.1.0.mjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.6-directbash-k6.1.0.mjs -o fortune-nyx-v1.5.6-directbash-k6.1.0.mjs && node fortune-nyx-v1.5.6-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.4-ssh.cjs -o fortune-nyx-v1.5.4-ssh.cjs && node fortune-nyx-v1.5.4-ssh.cjs
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.6-ssh.cjs -o fortune-nyx-v1.5.6-ssh.cjs && node fortune-nyx-v1.5.6-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.4-ssh-nosftp.js -o fortune-nyx-v1.5.4-ssh-nosftp.js && node fortune-nyx-v1.5.4-ssh-nosftp.js
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/builds/fortune-nyx-v1.5.6-ssh-nosftp.js -o fortune-nyx-v1.5.6-ssh-nosftp.js && node fortune-nyx-v1.5.6-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.4-directbash-k6.1.0.mjs` options:**
+**`fortune-nyx-v1.5.6-directbash-k6.1.0.mjs` options:**
 
 ```bash
-node fortune-nyx-v1.5.4-directbash-k6.1.0.mjs                  # boot as root
-node fortune-nyx-v1.5.4-directbash-k6.1.0.mjs --user alice     # boot as alice (prompts for password if set)
-node fortune-nyx-v1.5.4-directbash-k6.1.0.mjs --user=alice     # same, inline form
-SSH_MIMIC_HOSTNAME=my-box node fortune-nyx-v1.5.4-directbash-k6.1.0.mjs  # custom hostname
+node fortune-nyx-v1.5.6-directbash-k6.1.0.mjs                  # boot as root
+node fortune-nyx-v1.5.6-directbash-k6.1.0.mjs --user alice     # boot as alice (prompts for password if set)
+node fortune-nyx-v1.5.6-directbash-k6.1.0.mjs --user=alice     # same, inline form
+SSH_MIMIC_HOSTNAME=my-box node fortune-nyx-v1.5.6-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.4-web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
+| `builds/fortune-nyx-v1.5.6-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.4-web.min.js`** — lightweight shell with IndexedDB VFS:
+**`fortune-nyx-v1.5.6-web.min.js`** — lightweight shell with IndexedDB VFS:
 
 ```html
 <script type="module">
-  import { createWebShell } from "./builds/fortune-nyx-v1.5.4-web.min.js";
+  import { createWebShell } from "./builds/fortune-nyx-v1.5.6-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.4-web.min.js`** — mirrors the `VirtualShell` programmatic API:
+**`fortune-nyx-v1.5.6-web.min.js`** — mirrors the `VirtualShell` programmatic API:
 
 ```html
 <script type="module">
-  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.5.4-web.min.js";
+  import { createVirtualShellShim } from "./builds/fortune-nyx-v1.5.6-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 (106)</strong></summary>
+<summary><strong>Built-in Commands (118)</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 106 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 118 commands are documented.
 
 ### Navigation
 
@@ -1003,7 +495,7 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `cat <path...>` | `-n` `-b` | Concatenate and print; `-n` numbers lines, `-b` numbers non-blank |
 | `chmod <mode> <file>` | | Octal (`755`) or symbolic (`+x`, `u+x`, `go-w`, `a=rx`) |
 | `cp <src> <dest>` | `-r` | Copy file or directory |
-| `find [path]` | `-name` `-type` | Search for files |
+| `find [path]` | `-name` `-iname` `-type` `-maxdepth` `-mindepth` `-exec` `-not` `-o` `-a` `-empty` `-size` | Search for files |
 | `ln <target> <link>` | `-s` | Hard or symbolic link |
 | `readlink <path>` | `-f` | Print resolved path of symbolic link |
 | `mkdir <path>` | `-p` | Create directory |
@@ -1017,13 +509,13 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 
 | Command | Flags | Description |
 |---------|-------|-------------|
-| `awk [-F <sep>] '<prog>'` | | Pattern scanning |
+| `awk [-F <sep>] '<prog>'` | `-v var=val` | Pattern scanning — NR/NF, `BEGIN`/`END`, field assign, `gsub`/`sub`/`substr`/`split`/`length`, `printf` |
 | `base64` | `-d` | Encode/decode base64 |
 | `cut` | `-d` `-f` | Remove sections from lines |
 | `diff <f1> <f2>` | | Compare files line by line |
 | `grep <pattern> [files]` | `-i` `-v` `-n` `-r` | Search file content |
 | `head [files]` | `-n <N>` | First N lines |
-| `sed -e 's/pat/rep/[g]'` | `-i` | Stream editor |
+| `sed -e 's/pat/rep/[g]'` | `-n` `-i` `-e` | Stream editor — `s///[gI]`, `d`, `p`, `=`, `q`, line/regex/range addresses |
 | `sort [files]` | `-r` `-n` `-u` | Sort lines |
 | `tail [files]` | `-n <N>` | Last N lines |
 | `tee [files]` | `-a` | Read stdin, write to stdout and files |
@@ -1039,8 +531,10 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 
 | Command | Flags | Description |
 |---------|-------|-------------|
-| `gzip <file>` / `gunzip <file>` | | Compress / decompress |
-| `tar <archive> [files]` | `-czf` `-xzf` `-tf` | Archive utility |
+| `gzip <file>` / `gunzip <file>` | `-k` `-d` | Compress / decompress (real gzip, browser-native) |
+| `bzip2 <file>` / `bunzip2 <file>` | `-k` `-d` | Compress / decompress bzip2 (VFS round-trip) |
+| `zip [-r] <archive> <files>` / `unzip <archive>` | `-l` `-d <dir>` | Real PKZIP + DEFLATE (interoperable) |
+| `tar <archive> [files]` | `-czf` `-xzf` `-tf` `-v` | Archive utility — real POSIX ustar binary format (interoperable) |
 
 ### System
 
@@ -1068,6 +562,9 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `python3` | `--version` `-c` `-V` | Virtual Python 3 interpreter; alias `python`; **requires `apt install python3`** |
 | `sleep <seconds>` | | Delay execution |
 | `uname` | `-a` `-r` `-m` | System information |
+| `bc` | | Arithmetic calculator (integer; `+` `-` `*` `/` `%` `**` `()`) |
+| `lsof` | `-i` | List open files (simulated) |
+| `strace <cmd>` | `-e` `-o` | Trace system calls (stub with realistic output) |
 | `uptime` | `-p` `-s` | Running time |
 | `w` | | Who is logged on and what they are doing |
 | `who` | | Active sessions |
@@ -1094,12 +591,16 @@ Type `help` in the shell for a grouped, colorized listing. Type `help <command>`
 | `false` | | Return exit code 1 |
 | `help [command]` | | List commands or show command usage |
 | `history [n]` | | Command history |
+| `jobs` | | List active jobs |
+| `bg [%n]` | | Resume job in background |
+| `fg [%n]` | | Resume job in foreground |
 | `man <command>` | | Command reference manual |
 | `printf <fmt> [args...]` | | Format and print (`%s` `%d` `%f` `%x` `\n` `\t`) |
 | `read [-r] <var...>` | `-r` `-p` | Read stdin into variable(s) |
 | `return [n]` | | Return from shell function |
-| `set [VAR=val]` | | Display or set shell variables |
-| `sh` | `-c <script>` `[file]` | Execute shell script — `if`/`for`/`while`/`case`/functions, `$((expr))`, single-quote-safe |
+| `set [VAR=val]` | `-e` `-x` `+e` `+x` | Display or set shell variables; `-e` exit on error, `-x` trace execution |
+| `sh` | `-c <script>` `[file]` | Execute shell script — `if`/`for`/`while`/`until`/`case`/functions, arrays `arr=(a b c)`, `$((expr))`, single-quote-safe |
+| `perl` | `-e` `-p` `-n` | One-liner interpreter (`print`/`say`, `s///`, `-p`/`-n` loop) |
 | `shift [n]` | | Shift positional parameters |
 | `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` |
@@ -1143,7 +644,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 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.
+**ℹ️ All 118 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)`.
 
@@ -1178,8 +679,22 @@ echo "${UNSET:-default}"     # default
 echo "${NAME:+alternate}"    # alternate (only if NAME is set)
 echo "${UNSET:=assigned}"    # assigns and returns "assigned"
 echo "${#NAME}"              # 5 (string length)
+echo "${NAME:2}"             # rld (substring from offset 2)
+echo "${NAME:1:3}"           # orl (substring offset 1, length 3)
+echo "${NAME/o/0}"           # w0rld (replace first)
+echo "${NAME//l/L}"          # worLd  (replace all)
+echo "${PATH##*/}"           # strip longest prefix match
+echo "${FILE%.txt}"          # strip shortest suffix match
 echo "$?"                    # last exit code
+echo "$RANDOM"               # random integer 0–32767
+echo "$LINENO"               # current line number
 echo ~                       # /home/<user> (tilde expansion)
+
+# Arrays
+arr=(alpha beta gamma)
+echo "${arr[0]}"             # alpha
+echo "${arr[@]}"             # alpha beta gamma
+echo "${#arr[@]}"            # 3
 ```
 
 > **Single-quote isolation** — `$VAR` and `$((...))` are never expanded inside `'...'`.
@@ -1219,6 +734,12 @@ while [ $COUNT -lt 3 ]; do
   echo "Count: $COUNT"
   COUNT=$((COUNT + 1))
 done
+
+COUNT=5
+until [ $COUNT -eq 0 ]; do
+  echo "Countdown: $COUNT"
+  COUNT=$((COUNT - 1))
+done
 ```
 
 ### Functions and case
@@ -1236,6 +757,30 @@ case "$1" in
 esac
 ```
 
+### Heredoc
+
+```bash
+cat << EOF
+line one
+line two
+EOF
+
+# write to file
+cat > /tmp/config << EOF
+HOST=localhost
+PORT=3000
+EOF
+```
+
+### set -e / set -x
+
+```bash
+set -e          # exit immediately on any non-zero exit code
+set -x          # print each command before executing (trace)
+set +e          # disable errexit
+set +x          # disable xtrace
+```
+
 ### Script Files
 
 ```typescript
@@ -1248,9 +793,13 @@ done
 await client.exec("sh /usr/local/bin/setup.sh");
 ```
 
-### .bashrc
+### Login Files
+
+Sourced automatically at session start, in order:
 
-Sourced automatically on every interactive session from `/home/<user>/.bashrc`:
+1. `/etc/environment` — `KEY=VALUE` pairs only, no shell syntax
+2. `~/.profile` — user login script
+3. `~/.bashrc` — interactive shell config
 
 ```bash
 export EDITOR=nano
@@ -1258,6 +807,20 @@ alias ll="ls -l"
 echo "Welcome, $USER!"
 ```
 
+### Line Editing
+
+Interactive shell supports full readline-style key bindings:
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Move cursor left / right |
+| `Home` / `Ctrl+A` | Jump to start of line |
+| `End` / `Ctrl+E` | Jump to end of line |
+| `Ctrl+K` | Kill to end of line |
+| `Ctrl+U` | Kill to start of line |
+| `Ctrl+W` | Kill word backward |
+| `!!` | Expand to last command |
+
 </details>
 
 ---
@@ -1666,18 +1229,21 @@ 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] 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] 118 built-in commands across 11 categories (added `zip`, `unzip`, `bzip2`, `bunzip2`, `lsof`, `strace`, `perl`, `w`, `ip`, `dmesg`, `last`, `basename`, `dirname`, `file`, `tput`, `stty`, `yes`, `fortune`, `cowsay`, `cowthink`, `cmatrix`, `sl`, `bc`, `jobs`, `bg`, `fg`)
+- [x] Real shell interpreter — `if`/`for`/`while`/`until`/`case`/functions, arrays `arr=(...)`, `$(cmd)`, `$((expr))`, `${#VAR}`, `${var#pfx}` `${var##pfx}` `${var%sfx}` `${var%%sfx}` `${var/p/r}` `${var//p/r}` `${var:off:len}` `${arr[@]}`, `{a,b,c}` brace expansion, `{1..N}` ranges, `*.glob` expansion, `!!` history expansion, `\` line continuation, `2>/dev/null` stderr redirect, `2>&1`, `(( x++ ))`, heredoc `<< EOF`, `set -e`/`set -x`, `$RANDOM`/`$LINENO`
 - [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.4-web.min.js`) — fully browser-native with IndexedDB VFS
-- [x] Self-standalone CLI (`fortune-nyx-v1.5.4-directbash-k6.1.0.mjs`) — single-file interactive shell, per-user history, tab completion
+- [x] Web shell bundles (`fortune-nyx-v1.5.6-web.min.js`) — fully browser-native with IndexedDB VFS
+- [x] Self-standalone CLI (`fortune-nyx-v1.5.6-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)
+- [x] Full readline line editing — `Ctrl+A/E/K/U/W`, `Home`/`End`, `!!` history expansion, `/etc/environment` + `~/.profile` login sourcing
+- [x] Interoperable archive formats — `tar` writes real POSIX ustar binary; `zip`/`unzip` use PKZIP+DEFLATE (fflate); files extracted by real system tools via SFTP
+- [x] Overhauled `sed` — `d`/`p`/`=`/`q`, `-n` suppress, line/regex/range/`$` addresses; overhauled `awk` — `-v`, field assignment, `gsub`/`sub`/`substr`/`split`/`length`/`printf`/`next`; overhauled `find` — `-exec`, `-maxdepth`, `-iname`, `-not`/`!`, `-o`/`-a`, `-empty`, `-size`
 - [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)