typescript-virtual-container 1.2.8 → 1.3.0

package/.vscode/settings.json

@@ -12,7 +12,6 @@
         
         "LICENSE": true,
         "*.md": true,
-        "biome.json": true,
         "tsconfig.tsbuildinfo": true
     }
 }

package/README.md

@@ -1,6 +1,6 @@
 # `typescript-virtual-container`
 
-> Pure in-memory SSH/SFTP server with a virtual filesystem, a real shell interpreter, and a typed programmatic API for testing, automation, honeypots, and interactive shell scripting in TypeScript/JavaScript.
+> Pure in-memory SSH/SFTP server with a realistic Linux rootfs, a virtual package manager, a real shell interpreter, and a typed programmatic API for testing, automation, honeypots, and interactive shell scripting in TypeScript/JavaScript.
 
 [![npm version](https://badge.fury.io/js/typescript-virtual-container.svg)](https://www.npmjs.com/package/typescript-virtual-container)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -23,10 +23,13 @@
   - [VirtualFileSystem](#virtualfilesystem)
   - [VFSB Binary Format](#vfsb-binary-format)
   - [VirtualUserManager](#virtualusermanager)
+  - [VirtualPackageManager](#virtualpackagemanager)
   - [HoneyPot](#honeypot)
   - [SshClient](#sshclient-programmatic-api)
   - [Key Types](#key-types)
 - [Usage Examples](#usage-examples)
+- [Linux Rootfs](#linux-rootfs)
+- [Package Manager (apt/dpkg)](#package-manager-aptdpkg)
 - [Built-in Commands](#built-in-commands)
 - [Shell Scripting](#shell-scripting)
 - [Configuration](#configuration)
@@ -57,7 +60,11 @@
 - **`.bashrc` support**: Loaded automatically at interactive session start from `/home/<user>/.bashrc`.
 - **Event-Driven Architecture**: All core classes extend `EventEmitter` for lifecycle and operation tracking.
 - **Security Auditing**: Built-in `HoneyPot` utility for comprehensive activity logging, event tracking, statistics collection, and anomaly detection across all components.
-- **60+ Built-in Commands**: Full navigation, text processing, archiving, system info, and user management commands — grouped and documented in the interactive `help` system.
+- **Linux rootfs on boot**: Realistic `/etc`, `/proc`, `/sys`, `/dev`, `/usr`, `/var` hierarchy populated at startup — `os-release`, `passwd`, `hosts`, `resolv.conf`, `/proc/meminfo`, `/proc/cpuinfo`, and more.
+- **Virtual package manager**: `apt install`, `apt remove`, `apt search`, `dpkg -l`, `dpkg -s` — 25 packages in the built-in registry (vim, git, nodejs, python3, curl, openssh, gcc…). Writes files into VFS, tracks state in `/var/lib/dpkg/status`.
+- **87 Built-in Commands**: Full navigation, text processing, archiving, system info, package management, and user management commands — grouped and documented in the interactive `help` system.
+- **`$(cmd)` command substitution**: Nested command execution in any argument position.
+- **Alias support**: `alias`, `unalias` — persisted in session environment.
 - **Full TypeScript Support**: Complete JSDoc coverage, exported types, and first-class async/await for all operations.
 
 ---
@@ -74,10 +81,10 @@
 ### What This Is Not
 
 - Not a fully isolated container runtime.
-- Not a security sandbox — the VFS does not sandbox host filesystem access by spawned child processes (e.g. `wget`, `curl` delegate to the host binary).
 - Not a kernel-level isolation boundary (unlike Docker/VM-based isolation).
+- Package stubs (e.g. `node`, `python3`) write files into the VFS and are visible to `which`/`dpkg -L`, but do not execute real binaries — the shell is pure TypeScript with no `execvp`.
 
-This project emulates shell behavior for developer workflows. It is designed for realism and productivity, not hard security isolation.
+This project emulates shell behavior for developer workflows. `curl` and `wget` use the native `fetch()` API (no host binary). All other network and execution primitives are simulated. It is designed for realism and deployability, not kernel-level security isolation.
 
 ---
 
@@ -382,12 +389,14 @@ new VirtualShell(
 
 ```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"
+  kernel: string;  // Kernel version string — shown by uname, neofetch, /proc/version
+  os: string;      // Full OS description — shown by neofetch, /etc/os-release, lsb_release
+  arch: string;    // CPU architecture label — shown by uname -m, neofetch
 }
 ```
 
+Fields map directly to the values reported by `uname -a`, `neofetch`, `lsb_release`, `/etc/os-release`, and `/proc/version` inside the shell. Changing them after construction has no effect — pass them to the constructor.
+
 **Example:**
 
 ```typescript
@@ -407,13 +416,26 @@ const shell = new VirtualShell("typescript-vm", {
 |--------|-------------|
 | `ensureInitialized(): Promise<void>` | Await this before using the shell 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)` | Start an SSH interactive session. |
-| `writeFileAsUser(authUser, path, content)` | Write a file with quota enforcement. |
+| `executeCommand(rawInput, authUser, cwd)` | Run a raw command string (supports `&&`, `\|`, `$(cmd)`, aliases). |
+| `startInteractiveSession(stream, authUser, sessionId, remoteAddress, terminalSize)` | Attach an interactive PTY session to this shell. |
+| `writeFileAsUser(authUser, path, content)` | Write a file on behalf of a user with quota enforcement. |
+| `refreshProcFs(): void` | Refresh `/proc/uptime`, `/proc/meminfo`, `/proc/cpuinfo`, etc. from live host data. |
+| `syncPasswd(): void` | Sync `/etc/passwd`, `/etc/group`, `/etc/shadow` from `VirtualUserManager` state. |
 | `getVfs(): VirtualFileSystem \| null` | Access the VFS instance. |
 | `getUsers(): VirtualUserManager \| null` | Access the user manager. |
 | `getHostname(): string` | Returns the configured hostname. |
 
+#### Public fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `vfs` | `VirtualFileSystem` | Backing virtual filesystem — use for direct path operations. |
+| `users` | `VirtualUserManager` | Virtual user database — auth, quotas, and session tracking. |
+| `packageManager` | `VirtualPackageManager` | APT/dpkg package manager backed by the built-in registry. |
+| `hostname` | `string` | Hostname shown in the shell prompt and SSH ident string. |
+| `properties` | `ShellProperties` | Distro identity strings surfaced by `uname`, `neofetch`, etc. |
+| `startTime` | `number` | Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. |
+
 **Custom command example:**
 
 ```typescript
@@ -665,25 +687,27 @@ new VirtualUserManager(
 |--------|-------------|
 | `initialize(): Promise<void>` | Load users/sudoers from VFS, ensure root exists. Call once on startup. |
 | `verifyPassword(username, password): boolean` | Check plaintext password against stored hash. |
-| `hasPassword(username): boolean` | Returns true if a password is set for the user. |
-| `hashPassword(password): string` | Hash a password using the configured algorithm. |
+| `hasPassword(username): boolean` | Returns `true` if a non-empty password is set for the user. |
+| `hashPassword(password): string` | Hash a password using scrypt (or SHA-256 with `SSH_MIMIC_FAST_PASSWORD_HASH=1`). |
+| `getPasswordHash(username): string \| null` | Returns the raw stored hash for a user, or `null` if not found. |
 | `addUser(username, password): Promise<void>` | Create user with home directory. |
-| `deleteUser(username): Promise<void>` | Delete user. Cannot delete root. |
-| `setPassword(username, password): Promise<void>` | Update password for an existing user. |
-| `isSudoer(username): boolean` | Check if user has sudo privileges. |
-| `addSudoer(username): Promise<void>` | Grant sudo privileges. |
-| `removeSudoer(username): Promise<void>` | Revoke sudo privileges. Cannot remove root. |
+| `deleteUser(username): Promise<void>` | Delete user. Throws when user is `root` or does not exist. |
+| `setPassword(username, password): Promise<void>` | Update password for an existing user. Throws when user does not exist. |
+| `isSudoer(username): boolean` | Returns `true` when the user has sudo privileges. |
+| `addSudoer(username): Promise<void>` | Grant sudo privileges. Throws when user does not exist. |
+| `removeSudoer(username): Promise<void>` | Revoke sudo privileges. Throws when username is `root`. |
 | `setQuotaBytes(username, maxBytes): Promise<void>` | Set per-user write quota (bytes under `/home/<user>`). |
-| `clearQuota(username): Promise<void>` | Remove quota limit. |
-| `getQuotaBytes(username): number \| null` | Returns quota in bytes, or null if unlimited. |
+| `clearQuota(username): Promise<void>` | Remove quota limit for a user. |
+| `getQuotaBytes(username): number \| null` | Returns quota in bytes, or `null` if unlimited. |
 | `getUsageBytes(username): number` | Returns current usage in bytes under `/home/<user>`. |
 | `assertWriteWithinQuota(username, path, content)` | Throws if the write would exceed the user's quota. |
+| `listUsers(): string[]` | Returns a sorted list of all registered usernames. |
 | `addAuthorizedKey(username, algo, data)` | Register an SSH public key for the user. |
 | `getAuthorizedKeys(username)` | Returns the list of authorized keys for a user. |
 | `removeAuthorizedKeys(username)` | Revoke all authorized keys for a user. |
-| `registerSession(username, remoteAddress): VirtualActiveSession` | Start session tracking, returns session descriptor. |
-| `unregisterSession(sessionId): void` | End session. Safe to call with null. |
-| `updateSession(sessionId, username, remoteAddress): void` | Update session metadata (used by `su`/`sudo`). |
+| `registerSession(username, remoteAddress): VirtualActiveSession` | Register an active session and allocate a virtual TTY. |
+| `unregisterSession(sessionId): void` | Remove a session record on disconnect. Safe to call with `null`. |
+| `updateSession(sessionId, username, remoteAddress): void` | Update session metadata after `su`/`sudo` identity change. |
 | `listActiveSessions(): VirtualActiveSession[]` | Returns all active sessions sorted by start time. |
 
 #### Events
@@ -712,6 +736,125 @@ users.on("session:register", ({ sessionId, username, remoteAddress }) => {
 
 ---
 
+
+### `VirtualPackageManager`
+
+Simulates APT/dpkg package management backed by a built-in registry. Accessed via `shell.packageManager`.
+
+#### Constructor
+
+Instantiated automatically by `VirtualShell`. Not constructed directly.
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `load()` | Load installed packages from `/var/lib/dpkg/status` (called on shell init) |
+| `install(names, opts?)` | Install packages (resolves deps, writes files to VFS). Returns `{ output, exitCode }` |
+| `remove(names, opts?)` | Remove packages. `opts.purge` also removes config files |
+| `search(term)` | Search available packages by name or description |
+| `show(name)` | Show dpkg-style metadata block for a package |
+| `listInstalled()` | List all installed packages as `InstalledPackage[]` |
+| `listAvailable()` | List all packages in the registry |
+| `isInstalled(name)` | Returns `true` if package is installed |
+| `installedCount()` | Count of installed packages (used by `neofetch`) |
+| `findInRegistry(name)` | Look up a `PackageDefinition` by name |
+
+#### Types
+
+```ts
+interface PackageDefinition {
+  name: string;
+  version: string;
+  description: string;
+  files?: PackageFile[];          // written to VFS on install
+  depends?: string[];             // resolved recursively
+  onInstall?: (vfs, users) => void;
+  onRemove?: (vfs) => void;
+}
+
+interface InstalledPackage {
+  name: string;
+  version: string;
+  architecture: string;
+  installedAt: string;            // ISO-8601
+  files: string[];                // paths written to VFS
+}
+```
+
+---
+
+### Snapshot Diff Tooling
+
+Three utility functions for comparing VFS snapshots in tests and deployment verification.
+
+```typescript
+import {
+  diffSnapshots,
+  formatDiff,
+  assertDiff,
+} from "typescript-virtual-container";
+```
+
+#### `diffSnapshots(before, after, options?): VfsDiff`
+
+Compares two snapshots and returns structured diff results.
+
+```ts
+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"],  // skip volatile paths
+});
+
+diff.clean;       // false
+diff.added;       // [{ path: "/usr/bin/vim", type: "file" }, ...]
+diff.removed;     // []
+diff.modified;    // [{ path: "/var/lib/dpkg/status", before: "...", after: "..." }]
+```
+
+#### `formatDiff(diff, options?): string`
+
+Human-readable output similar to `git diff --stat`.
+
+```ts
+console.log(formatDiff(diff));
+// + /app  [directory]
+// + /usr/bin/vim  [file]
+// ~ /var/lib/dpkg/status  [modified]
+//
+// 2 added, 1 modified
+
+console.log(formatDiff(diff, { showContent: true, maxContentChars: 80 }));
+```
+
+#### `assertDiff(diff, expected): void`
+
+Throws on mismatch — designed for test suites.
+
+```ts
+assertDiff(diff, {
+  added:    ["/app", "/usr/bin/vim"],
+  modified: ["/var/lib/dpkg/status"],
+});
+// throws if any expected path is not in the diff
+```
+
+#### Types
+
+```ts
+interface VfsDiff {
+  added:    VfsDiffEntry[];      // { path, type }
+  removed:  VfsDiffEntry[];      // { path, type }
+  modified: VfsDiffModified[];   // { path, type, before, after }
+  clean:    boolean;
+}
+```
+
+---
+
 ### `HoneyPot`
 
 Comprehensive security auditing and event tracking utility. Attaches listeners to all core components to log activity, track statistics, and detect anomalies.
@@ -966,6 +1109,49 @@ interface VfsSnapshot {
 
 ---
 
+### Command Helpers
+
+Three utility functions are exported from `typescript-virtual-container` to assist with argument parsing inside custom command handlers.
+
+#### `ifFlag(args, flags): boolean`
+
+Returns `true` when any of the given flags appear in the argument array. Matches both standalone tokens (`-s`, `--silent`) and inline forms (`--output=file`).
+
+```typescript
+import { ifFlag } from "typescript-virtual-container";
+
+const recursive = ifFlag(args, ["-r", "--recursive"]);
+const silent    = ifFlag(args, "-s");
+```
+
+#### `getFlag(args, flags): string | true | undefined`
+
+Returns the value of a flag, `true` if the flag has no value, or `undefined` if absent.
+
+```typescript
+import { getFlag } from "typescript-virtual-container";
+
+const output = getFlag(args, ["-o", "--output"]);
+// args = ["--output", "file.txt"] → "file.txt"
+// args = ["--output=file.txt"]    → "file.txt"
+// args = ["--verbose"]            → true  (when "verbose" is in flags list)
+// args = []                       → undefined
+```
+
+#### `getArg(args, index, options?): string | undefined`
+
+Returns the positional argument at a given zero-based index, skipping known flags and their values.
+
+```typescript
+import { getArg } from "typescript-virtual-container";
+
+// args = ["-r", "src", "dest"]
+const src  = getArg(args, 0, { flags: ["-r"] }); // "src"
+const dest = getArg(args, 1, { flags: ["-r"] }); // "dest"
+```
+
+---
+
 ## Usage Examples
 
 ### Example 1: Basic SSH Server
@@ -1316,6 +1502,148 @@ const [r1, r2] = await Promise.all([
 ]);
 ```
 
+---
+
+## Linux Rootfs
+
+On every `VirtualShell` init, a realistic Linux directory hierarchy is bootstrapped into the VFS. All paths are created idempotently — FS-mode snapshots survive restarts without duplication.
+
+### Directory layout
+
+```
+/
+├── bin -> /usr/bin          (symlink, Debian-style)
+├── dev/                     null, zero, random, urandom, pts/, shm/
+├── etc/
+│   ├── apt/sources.list     Fortune package sources
+│   ├── debian_version
+│   ├── group                synced from VirtualUserManager
+│   ├── hostname
+│   ├── hosts                127.0.0.1 localhost + VM hostname
+│   ├── motd
+│   ├── 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 (based on pts/* TTY)
+│   ├── self/                mirrors the most recent session's /proc/<pid>/
+│   ├── cpuinfo              real host CPU info
+│   ├── loadavg
+│   ├── meminfo              real host memory
+│   ├── net/dev              eth0 + lo
+│   ├── uptime               shell uptime in seconds
+│   └── version              kernel from ShellProperties
+├── root/                    root home + .bashrc
+├── sys/devices/virtual/dmi/id/
+│   ├── sys_vendor           "Fortune Systems"
+│   └── product_name         "VirtualContainer v1"
+├── tmp/                     (mode 0o1777 sticky)
+├── usr/bin/                 stubs for all built-in commands
+├── var/
+│   ├── lib/dpkg/status      managed by VirtualPackageManager
+│   └── log/                 syslog, auth.log, dpkg.log, apt/
+└── ...
+```
+
+### API
+
+```ts
+shell.refreshProcFs();   // refresh /proc/* with current system state
+shell.syncPasswd();      // sync /etc/passwd|group|shadow from VirtualUserManager
+```
+
+`syncPasswd()` is called automatically on `bootstrapLinuxRootfs`. Call it again after `users.addUser()` / `users.deleteUser()` to keep `/etc/passwd` consistent.
+
+---
+
+## Package Manager (apt/dpkg)
+
+A pure-TypeScript APT/dpkg simulation backed by a built-in package registry. No external process is spawned.
+
+### Workflow
+
+```
+apt install <pkg>   → resolves deps → writes files to VFS → updates /var/lib/dpkg/status
+apt remove <pkg>    → removes VFS files → updates status
+dpkg -l             → reads installed packages from VirtualPackageManager
+```
+
+### Built-in package registry (25 packages)
+
+| Package | Version | Section |
+|---------|---------|---------|
+| `vim` | 2:9.0.1378-2 | editors |
+| `git` | 1:2.39.2-1 | vcs |
+| `python3` | 3.11.2-1 | python |
+| `nodejs` | 18.19.0 | javascript |
+| `npm` | 9.2.0 | javascript |
+| `curl` | 7.88.1-10 | web |
+| `wget` | 1.21.3-1 | web |
+| `htop` | 3.2.2-2 | utils |
+| `openssh-client` | 1:9.2p1-2 | net |
+| `openssh-server` | 1:9.2p1-2 | net |
+| `net-tools` | 2.10-0.1 | net |
+| `iputils-ping` | 3:20221126-1 | net |
+| `jq` | 1.6-2.1 | utils |
+| `build-essential` | 12.9 | devel |
+| `gcc` | 4:12.2.0-3 | devel |
+| `g++` | 4:12.2.0-3 | devel |
+| `make` | 4.3-4.1 | devel |
+| `less` | 590-2 | text |
+| `unzip` | 6.0-28 | utils |
+| `rsync` | 3.2.7-1 | net |
+| `tmux` | 3.3a-3 | utils |
+| `tree` | 2.1.0-1 | utils |
+| `ca-certificates` | 20230311 | misc |
+| `sudo` | 1.9.13p3-1 | admin |
+| `systemd` | 252.22-1 | admin |
+
+> **Note on package stubs**: installing `nodejs` or `python3` writes stubs into `/usr/bin/` and makes them discoverable via `which` and `dpkg -L`. The stubs print a version line but do not execute real binaries — the shell runtime is pure TypeScript with no `execvp`. This makes them useful for testing install workflows and `which`/`dpkg -L` queries, not for running actual scripts.
+
+### `VirtualPackageManager` API
+
+```ts
+// Access via shell instance
+const pm = shell.packageManager;
+
+pm.install(["vim", "git"], { quiet: false })   // → { output, exitCode }
+pm.remove(["vim"], { purge: false })           // → { output, exitCode }
+pm.search("editor")                            // → PackageDefinition[]
+pm.show("vim")                                 // → string (dpkg-style block)
+pm.listInstalled()                             // → InstalledPackage[]
+pm.listAvailable()                             // → PackageDefinition[]
+pm.isInstalled("vim")                          // → boolean
+pm.installedCount()                            // → number
+pm.findInRegistry("nodejs")                    // → PackageDefinition | undefined
+```
+
+### Registering custom packages
+
+```ts
+import { VirtualPackageManager } from "typescript-virtual-container";
+
+// Custom packages can be added to the registry before shell init
+// by extending PACKAGE_REGISTRY or by calling install() with custom defs.
+
+// Or: register a post-install hook via onInstall
+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);
+  },
+};
+```
+
+
 ---
 
 ## Built-in Commands
@@ -1327,7 +1655,7 @@ All commands are available in SSH shell mode and via `SshClient.exec()`. Type `h
 | Command | Flags | Description |
 |---------|-------|-------------|
 | `cd <path>` | | Change directory |
-| `ls [path]` | `-l` | List directory contents |
+| `ls [path]` | `-l` `-a` | List directory contents (`-a` shows dotfiles) |
 | `pwd` | | Print working directory |
 | `tree [path]` | | ASCII directory tree |
 
@@ -1335,14 +1663,15 @@ All commands are available in SSH shell mode and via `SshClient.exec()`. Type `h
 
 | Command | Flags | Description |
 |---------|-------|-------------|
-| `cat <path>` | | Print file contents |
-| `chmod <mode> <file>` | | Change file permissions (octal) |
+| `cat <path...>` | `-n` `-b` | Concatenate and print files; `-n` numbers all lines, `-b` numbers non-blank lines |
+| `chmod <mode> <file>` | | Change file permissions — octal (`755`) or symbolic (`+x`, `u+x`, `go-w`, `a=rx`) |
 | `cp <src> <dest>` | `-r` | Copy file or directory |
 | `find [path]` | `-name <pat>` `-type f\|d` | Search for files |
 | `ln <target> <link>` | `-s` | Create hard or symbolic link |
 | `mkdir <path>` | `-p` | Create directory |
 | `mv <src> <dest>` | | Move or rename |
 | `rm <path>` | `-r` | Remove file or directory |
+| `nano <path>` | | Interactive text editor |
 | `touch <path>` | | Create or update file |
 
 ### Text Processing
@@ -1384,9 +1713,14 @@ All commands are available in SSH shell mode and via `SshClient.exec()`. Type `h
 | `htop` | | System monitor (mock) |
 | `id [user]` | | Print user identity (uid/gid/groups) |
 | `kill [-9] <pid>` | | Send signal to process (mock) |
-| `neofetch` | | System info display (mock) |
+| `free` | `-h` `-m` `-g` | Display free and used memory |
+| `lsb_release` | `-a` `-i` `-d` `-r` `-c` | Print distribution information |
+| `neofetch` | | System info display (shows real packages/uptime) |
+| `node` | `--version` `-e` `-p` | JavaScript runtime (virtual REPL — evaluates expressions and VFS `.js` files) |
+| `python3` | `--version` `-c` `-V` | Python 3 interpreter (virtual REPL — evaluates expressions and VFS `.py` files); alias `python` |
+| `uptime` | `-p` `-s` | Tell how long the system has been running |
 | `ping [-c <n>] <host>` | | Send ICMP ECHO_REQUEST (mock) |
-| `ps` | `-a` `-u` `-x` | Report process status |
+| `ps` | `-a` `-u` `-x` `aux` | Report process status; `-u` / `aux` shows USER/PID/%CPU/%MEM columns |
 | `sleep <seconds>` | | Delay execution |
 | `uname` | `-a` `-r` `-m` | Print system information |
 | `who` | | List active sessions |
@@ -1396,22 +1730,51 @@ All commands are available in SSH shell mode and via `SshClient.exec()`. Type `h
 
 | Command | Flags | Description |
 |---------|-------|-------------|
-| `curl <url>` | | HTTP client (delegates to host binary) |
-| `wget <url>` | | File downloader (delegates to host binary) |
+| `curl <url>` | `-o` `-X` `-d` `-H` `-s` `-I` `-L` `-v` | HTTP client (pure `fetch()`, no host binary) |
+| `wget <url>` | `-O` `-P` `-q` | File downloader (pure `fetch()`, no host binary) |
 
 ### Shell
 
 | Command | Flags | Description |
 |---------|-------|-------------|
+| `alias [name=value]` | | Define or display aliases |
 | `clear` | | Clear terminal screen (full ANSI reset) |
-| `echo <text>` | | Display text |
+| `declare [name=value]` | `-i` `-r` `-x` | Declare variables with attributes; aliases `local`, `typeset` |
+| `echo <text>` | `-n` `-e` | Display text; `-n` suppresses newline, `-e` interprets `\n` `\t` `\r` `\\` |
 | `env` | | Print session environment variables |
-| `exit [code]` | | Exit session |
+| `exit [code]` | | Exit session with optional exit code |
 | `export NAME=VALUE` | | Set shell variable in current session |
-| `help [command]` | | List commands (grouped) or show command details |
+| `help [command]` | | List commands grouped by category, or show usage for a specific command |
+| `history [n]` | | Display command history (last N entries) |
+| `man <command>` | | Display command reference manual |
+| `printf <fmt> [args...]` | | Format and print data (`%s` `%d` `%f` `%x` `\n` `\t`) |
+| `read [-r] <var...>` | `-r` `-p` | Read a line from stdin into variable(s) |
+| `return [n]` | | Return from a shell function with optional exit code |
 | `set [VAR=val]` | | Display or set shell variables |
-| `sh` | `-c <script>` `[file]` | Execute shell script (supports if/for/while) |
+| `sh` | `-c <script>` `[file]` | Execute shell script — supports `if`/`for`/`while`/`case`/functions, bare `VAR=val` assignments, `$((expr))` arithmetic; single-quoted args are never expanded |
+| `shift [n]` | | Shift positional parameters left by n (default 1) |
+| `source <file>` | | Execute file in current shell environment; aliases and exports persist |
+| `. <file>` | | Alias for `source` |
+| `test <expr>` | | Evaluate POSIX conditional expression |
+| `[ <expr> ]` | | Alias for `test`; supports `-f` `-d` `-e` `-z` `-n` `-x` `-s` `=` `!=` `-eq` `-lt` `-gt` `-le` `-ge` `!` `-a` `-o` |
+| `trap [action] [signal]` | | Register handler for shell signals; supports `EXIT` |
+| `true` | | Return success exit code (0) |
+| `false` | | Return failure exit code (1) |
+| `type <command>` | | Describe how a command would be interpreted (builtin vs PATH) |
+| `unalias <name>` | `-a` | Remove alias definitions |
 | `unset <VAR>` | | Remove shell variable |
+| `which <command>` | | Locate a command in the session PATH |
+
+### Package Management
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `apt <cmd> [pkg...]` | | Package manager (`install`, `remove`, `purge`, `update`, `upgrade`, `search`, `show`, `list`) |
+| `apt-get <cmd>` | | Alias for `apt` |
+| `apt-cache <cmd>` | | Query package cache (`search`, `show`, `policy`) |
+| `dpkg` | `-l` `-s` `-L` `-r` `-P` | Debian package manager low-level tool |
+| `dpkg-query` | `-W` `-l` | Show information about installed packages |
+
 
 ### Users & Permissions
 
@@ -1419,7 +1782,6 @@ All commands are available in SSH shell mode and via `SshClient.exec()`. Type `h
 |---------|-------|-------------|
 | `adduser <name> <pass>` | | Create user (root only) |
 | `deluser <name>` | | Delete user (root only) |
-| `nano <path>` | | Interactive text editor |
 | `passwd [user]` | | Change password |
 | `su [user]` | | Switch user |
 | `sudo <cmd>` | `-i` | Run as root |
@@ -1454,11 +1816,34 @@ cat /tmp/out.txt >> /tmp/log.txt
 ```bash
 export NAME=world
 echo "Hello $NAME"           # Hello world
+echo "${NAME}"               # world (braced form)
 echo "${NAME:-fallback}"     # world (or fallback if unset)
-echo "${UNSET:-default}"     # default
-echo "Exit: $?"              # last exit code
+echo "${UNSET:-default}"     # default (assign-on-read: use ${UNSET:=default})
+echo "${NAME:+alternate}"    # alternate (only if NAME is set)
+echo "${#NAME}"              # 5 (string length)
+echo "$?"                    # last exit code
+echo "~"                     # /home/<user> (tilde expansion)
+```
+
+### Arithmetic Expansion
+
+```bash
+echo $((2 + 3))              # 5
+echo $((10 % 3))             # 1
+X=4; echo $((X * 2))         # 8
+i=0; i=$((i + 1)); echo $i   # 1
+
+# In loops (via sh):
+sh -c 'i=0
+while [ $i -lt 5 ]; do
+  echo $i
+  i=$((i + 1))
+done'
 ```
 
+> **Single-quote isolation** — variable and arithmetic expansion never occurs inside single quotes.
+> `echo '$NAME'` always outputs the literal string `$NAME`.
+
 ### Conditionals
 
 ```bash
@@ -1789,12 +2174,45 @@ MIT — see [LICENSE](./LICENSE).
 - [x] New commands: `sort`, `uniq`, `tee`, `cut`, `tr`, `xargs`, `diff`, `sed`, `awk`, `tar`, `gzip`, `gunzip`, `base64`, `date`, `sleep`, `id`, `groups`, `uname`, `ps`, `kill`, `df`, `du`, `ping`
 - [x] Structured event hooks (session open/close, file write, sudo challenge)
 - [x] Binary snapshot format (VFSB) — replaces JSON+base64, ~27% smaller, no string parsing overhead, backward-compatible JSON migration
-- [ ] Snapshot diff tooling for test assertions
+- [x] Linux rootfs on boot — `/etc`, `/proc`, `/sys`, `/dev`, `/usr`, `/var` populated at init; `os-release`, `passwd`, `hosts`, `/proc/meminfo`, `/proc/cpuinfo`, `/proc/version`, `/proc/uptime`, `/sys/devices/virtual/dmi/`, symlinks `/bin`→`/usr/bin`
+- [x] Virtual package manager — `apt install/remove/purge/update/upgrade/search/show/list`, `apt-get`, `apt-cache`, `dpkg`, `dpkg-query`; 25 packages in registry; writes files to VFS; `/var/lib/dpkg/status` persistence
+- [x] `curl` / `wget` reimplemented as pure `fetch()` — no host binary spawned, full isolation
+- [x] New commands: `which`, `type`, `man`, `uptime`, `free`, `lsb_release`, `alias`, `unalias`
+- [x] `$(cmd)` command substitution in variable expansion
+- [x] Alias expansion in command dispatch
+- [x] `neofetch` shows real package count and shell uptime
+- [x] `syncPasswd()` / `refreshProcFs()` public API on `VirtualShell`
+- [x] `test` / `[` — full POSIX conditional expressions (`-f`, `-d`, `-e`, `-z`, `-n`, `-x`, `-s`, `-L`, `=`, `!=`, `-eq`, `-lt`, `-gt`, `-le`, `-ge`, `!`, `-a`, `-o`)
+- [x] `source` / `.` — execute file in current shell env (aliases and exports persist across commands)
+- [x] `history [n]` — display command history from VFS `.bash_history`
+- [x] `echo -e` / `echo -n` — escape sequence interpretation and newline suppression
+- [x] `ls -a` — show dotfiles
+- [x] `chmod` symbolic modes — `+x`, `u+x`, `go-w`, `a=rx`, comma-separated
+- [x] `cat -n` / `-b` — line numbering, multi-file concatenation, stdin support
+- [x] `ping -c N` — respects packet count flag
+- [x] `ps -u` / `ps aux` — extended format with USER/PID/%CPU/%MEM/VSZ/RSS columns
+- [x] `$(cmd)` in single-quoted args preserved — `sh -c 'echo $(whoami)'` now works correctly
+- [x] Pipeline executor: `runCommandDirect` — args with `;`, `|`, `>` no longer re-parsed
+- [x] `>>` append redirect fixed — was broken because `echo` lacked terminal newline
+- [x] `export A=1 && echo $A` — env vars visible to subsequent commands in same pipeline
+- [x] `echo` uses session `env.vars` (not stale global store)
+- [x] `printf` — format string with `%s` `%d` `%f` `%x` `\n` `\t`
+- [x] `read` — read stdin into variables (supports multiple vars, splits on whitespace)
+- [x] `declare` / `local` / `typeset` — variable declaration with `-i` integer, `-r` readonly, `-x` export
+- [x] `shift [n]` — shift positional parameters
+- [x] `trap [action] [signal]` — signal handlers with `EXIT` support
+- [x] `return [n]` — return from shell functions
+- [x] `exit [code]` — optional exit code
+- [x] `help` rewrite — Package Management category, aliases shown inline, `help <cmd>` shows category
+- [x] Category corrections — `neofetch`→system, `nano`→files, `apt`/`dpkg`→package
+- [x] `src/utils/expand.ts` — centralised expansion module used by `runCommand`, `echo`, and `sh.ts`
+- [x] `${#VAR}` string length, `$((expr))` arithmetic, `~` tilde expansion
+- [x] `${VAR:=assign}` assign-on-read, `${VAR:+alternate}` alternate-if-set
+- [x] Single-quote isolation in expansion — `$VAR` never expanded inside `'...'`
+- [x] `true` / `false` builtins
+- [x] Bare `VAR=val` assignments in `sh` scripts (`i=0`, `i=$((i+1))`)
+- [x] `$?` reflects last command exit code correctly across `&&` / `;` chains
+- [x] `node` / `python3` virtual REPL stubs — `node -e`, `node <file>`, `python3 -c`, `python3 <file>`, `--version` flags
+- [x] `/proc/self` and `/proc/<pid>` per-session process entries — `comm`, `status`, `cmdline`, `environ`, `cwd`, `exe`, `fd/`
+- [x] Snapshot diff tooling — `diffSnapshots()`, `formatDiff()`, `assertDiff()` exported from `typescript-virtual-container`
 - [ ] WebSocket-based remote shell client (experimental)
-- [ ] `$(cmd)` command substitution in variable expansion
-
----
-
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md).