typescript-virtual-container 1.0.8 → 1.1.0

package/README.md

@@ -10,6 +10,7 @@
 ## Table of Contents
 
 - [Overview](#overview)
+- [What This Is / What This Is Not](#what-this-is--what-this-is-not)
 - [Why This Package](#why-this-package)
 - [Installation](#installation)
 - [Compatibility](#compatibility)
@@ -42,6 +43,22 @@
 - **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and a growing set of additional commands. Not everything is implemented yet, and shell compatibility is still being expanded.
 - **Full TypeScript Support**: Complete JSDoc coverage, exported types, and first-class async/await for all operations.
 
+## What This Is / What This Is Not
+
+### What This Is
+
+- A virtual shell runtime written in TypeScript.
+- An in-memory environment with its own virtual filesystem, user management, and command runtime.
+- A practical tool for deterministic testing, automation pipelines, and SSH-like workflows without running real containers.
+
+### What This Is Not
+
+- Not a fully isolated container runtime.
+- Not a security sandbox.
+- Not a kernel-level isolation boundary (unlike Docker/VM-based isolation).
+
+This project emulates shell behavior for developer workflows. It is designed for realism and productivity, not hard security isolation.
+
 ## Why This Package
 
 This package is designed for teams that need a realistic SSH-like runtime without spinning up real containers or VMs.
@@ -87,10 +104,10 @@ The virtual filesystem and shell behavior are intentionally portable and do not
 ### Running an SSH Server
 
 ```typescript
-import { VirtualMachine } from "typescript-virtual-container";
+import { VirtualSshServer } from "typescript-virtual-container";
 
 // Create server on port 2222
-const ssh = new VirtualMachine({ 
+const ssh = new VirtualSshServer({ 
 	port: 2222, 
 	hostname: "my-container" 
 });
@@ -112,13 +129,14 @@ process.on("SIGTERM", () => {
 ### Using the Programmatic Client API
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({ port: 2222 });
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
 // Create authenticated client for specific user
-const client = new SshClient(ssh, "root");
+const client = new SshClient(shell, "root");
 
 // Execute commands programmatically
 const list = await client.ls("/home");
@@ -178,7 +196,7 @@ ssh.stop();
 
 ### SshMimic (SSH Server)
 
-Main SSH server class. Manages virtual filesystem, user authentication, and session handlers.
+Main SSH server class, exported as `VirtualSshServer` in the package entrypoint. It wires the virtual shell runtime into ssh2 sessions and manages authentication/session handlers.
 
 #### Constructor
 
@@ -186,17 +204,25 @@ Main SSH server class. Manages virtual filesystem, user authentication, and sess
 new SshMimic(options: {
 	port: number;           // TCP port to bind on localhost
 	hostname?: string;      // Virtual hostname (default: "typescript-vm")
-	basePath?: string;      // Base directory for VFS snapshot storage (default: ".")
+	shell?: VirtualShell;   // Optional preconfigured shell instance
 })
 ```
 
+- `hostname` controls the SSH ident label and the default hostname used by a generated shell.
+- If `shell` is omitted, the server creates `new VirtualShell(hostname)` for you.
+
 **Example:**
 
 ```typescript
+const virtualShell = new VirtualShell("my-lab", {
+	kernel: "1.0.0+itsrealfortune+1-amd64",
+	os: "Fortune GNU/Linux x64",
+	arch: "x86_64",
+}, "./data");
 const ssh = new SshMimic({
 	port: 2222,
 	hostname: "my-lab",
-	basePath: "./data"  // Snapshots stored in ./data/.vfs/mirror.tar.gz
+	shell: virtualShell
 });
 ```
 
@@ -254,21 +280,22 @@ console.log(`Server name: ${ssh.getHostname()}`);
 
 ### SshClient (Programmatic Shell API)
 
-Execute shell commands as a specific user without SSH overhead. Maintains connection state (current working directory) across calls.
+Execute shell commands against a `VirtualShell` instance without SSH overhead. Maintains connection state (current working directory) across calls.
 
 #### Constructor
 
 ```typescript
-new SshClient(ssh: SshMimic, username: string)
+new SshClient(shell: VirtualShell, username: string)
 ```
 
-- **ssh**: Parent SSH server instance (must be started)
+- **shell**: Parent virtual shell instance
 - **username**: User to authenticate as (no password required)
 
 **Example:**
 
 ```typescript
-const client = new SshClient(ssh, "alice");
+const shell = new VirtualShell("typescript-vm");
+const client = new SshClient(shell, "alice");
 ```
 
 #### Methods
@@ -419,30 +446,57 @@ console.log(client.getUsername());  // Username from constructor
 
 ### VirtualShell
 
-Encapsulates shell execution primitives used by the SSH runtime for command dispatch and interactive sessions.
+Encapsulates shell execution primitives used by the SSH runtime for command dispatch, interactive sessions, and the programmatic client.
+
+#### ShellProperties
+
+```typescript
+interface ShellProperties {
+	kernel: string;
+	os: "Fortune GNU/Linux x64";
+	arch: "x86_64";
+}
+
+const defaultShellProperties: ShellProperties;
+```
+
+- `kernel` is displayed in shell/system information output.
+- `os` and `arch` are fixed labels used by the shell runtime.
 
 #### Constructor
 
 ```typescript
 new VirtualShell(
-	vfs: VirtualFileSystem,
-	users: VirtualUserManager,
 	hostname: string,
+	properties?: ShellProperties,
+	basePath?: string,
 )
 ```
 
-- **vfs**: Virtual filesystem instance used by shell commands.
-- **users**: User manager for authentication/session-aware command behavior.
 - **hostname**: Hostname injected into command context and prompt behavior.
+- **properties**: Optional shell metadata. Defaults to `defaultShellProperties`.
+- **basePath**: Optional directory used to resolve `.vfs/mirror.tar.gz` (defaults to `.`).
 
 **Example:**
 
 ```typescript
-const shell = new VirtualShell(vfs, users, "typescript-vm");
+const shell = new VirtualShell("typescript-vm", {
+	kernel: "1.0.0+itsrealfortune+1-amd64",
+	os: "Fortune GNU/Linux x64",
+	arch: "x86_64",
+}, "./data");
 ```
 
 #### Methods
 
+##### `addCommand(name: string, params: string[], callback: (ctx: CommandContext) => CommandResult | Promise<CommandResult>): void`
+
+Registers a custom command at runtime.
+
+```typescript
+shell.addCommand("hello", [], () => ({ stdout: "hello", exitCode: 0 }));
+```
+
 ##### `executeCommand(rawInput: string, authUser: string, cwd: string): void`
 
 Runs one command input in shell mode for a given user and working directory.
@@ -617,11 +671,12 @@ User authentication, password hashing (scrypt), sudo privilege management, and s
 #### Constructor
 
 ```typescript
-new VirtualUserManager(vfs: VirtualFileSystem, defaultRootPassword?: string)
+new VirtualUserManager(vfs: VirtualFileSystem, defaultRootPassword?: string, autoSudoForNewUsers?: boolean)
 ```
 
 - **vfs**: Virtual filesystem (for auth data persistence)
-- **defaultRootPassword**: Root password if creating new user (default: "root")
+- **defaultRootPassword**: Root password used when root is created (default: "root")
+- **autoSudoForNewUsers**: When true, new users are added to sudoers automatically (default: `true` unless `SSH_MIMIC_AUTO_SUDO_NEW_USERS` disables it)
 
 ```typescript
 const users = new VirtualUserManager(vfs, "SecureRootPass123");
@@ -801,9 +856,9 @@ interface VirtualActiveSession {
 Minimal server startup that accepts SSH connections:
 
 ```typescript
-import { VirtualMachine } from "typescript-virtual-container";
+import { VirtualSshServer } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({
+const ssh = new VirtualSshServer({
 	port: 2222,
 	hostname: "lab-environment"
 });
@@ -835,12 +890,13 @@ ssh root@localhost -p 2222
 Create, read, modify files without SSH:
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({ port: 2222 });
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
-const client = new SshClient(ssh, "root");
+const client = new SshClient(shell, "root");
 
 // Create structure
 await client.mkdir("/app/config", true);
@@ -874,9 +930,10 @@ ssh.stop();
 Create users, manage permissions, session tracking:
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({ port: 2222 });
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
 const users = ssh.getUsers()!;
@@ -891,11 +948,11 @@ await users.removeSudoer("bob");
 await users.addSudoer("alice");
 
 // Alice: High privilege
-const alice = new SshClient(ssh, "alice");
+const alice = new SshClient(shell, "alice");
 await alice.writeFile("/etc/important.conf", "secret=yes");
 
 // Bob: Regular user
-const bob = new SshClient(ssh, "bob");
+const bob = new SshClient(shell, "bob");
 const result = await bob.cat("/etc/important.conf");
 console.log("Bob read file:", result.stderr);
 
@@ -909,12 +966,13 @@ ssh.stop();
 Save filesystem state between runs:
 
 ```typescript
-import { VirtualMachine } from "typescript-virtual-container";
+import { VirtualSshServer, VirtualShell } from "typescript-virtual-container";
 
 // First run: Initialize
-const ssh1 = new VirtualMachine({ 
+const shell1 = new VirtualShell("typescript-vm", undefined, "./container");
+const ssh1 = new VirtualSshServer({ 
 	port: 2222,
-	basePath: "./container" 
+	shell: shell1 
 });
 await ssh1.start();
 const vfs1 = ssh1.getVfs()!;
@@ -927,9 +985,10 @@ ssh1.stop();
 console.log("State saved to ./container/.vfs/mirror.tar.gz");
 
 // Later: Reload and continue
-const ssh2 = new VirtualMachine({ 
+const shell2 = new VirtualShell("typescript-vm", undefined, "./container");
+const ssh2 = new VirtualSshServer({ 
 	port: 2223,
-	basePath: "./container" 
+	shell: shell2 
 });
 await ssh2.start();
 const vfs2 = ssh2.getVfs()!;
@@ -948,13 +1007,14 @@ ssh2.stop();
 Simulate filesystem changes and verify outcomes:
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
 async function testDeployment() {
-	const ssh = new VirtualMachine({ port: 2222 });
+	const shell = new VirtualShell("typescript-vm");
+	const ssh = new VirtualSshServer({ port: 2222, shell });
 	await ssh.start();
 
-	const client = new SshClient(ssh, "root");
+	const client = new SshClient(shell, "root");
 
 	// Pre-deployment: Set up base structure
 	await client.mkdir("/srv/app", true);
@@ -984,12 +1044,13 @@ testDeployment().catch(console.error);
 Simulate shell workflows:
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({ port: 2222 });
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
-const client = new SshClient(ssh, "root");
+const client = new SshClient(shell, "root");
 
 // Create nested structure
 await client.mkdir("/home/user/projects/myapp/src", true);
@@ -1026,12 +1087,13 @@ ssh.stop();
 Graceful error handling in programmatic workflows:
 
 ```typescript
-import { VirtualMachine, SshClient } from "typescript-virtual-container";
+import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
 
-const ssh = new VirtualMachine({ port: 2222 });
+const shell = new VirtualShell("typescript-vm");
+const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
-const client = new SshClient(ssh, "root");
+const client = new SshClient(shell, "root");
 
 // Try read non-existent file
 const result = await client.readFile("/etc/nonexistent.conf");
@@ -1056,32 +1118,42 @@ ssh.stop();
 
 ## Built-in Commands
 
-The following commands are available in both SSH shell mode and via `SshClient.exec()`. This list is intentionally incomplete: some commands, flags, and edge cases are still missing or only partially compatible with real shells, and that will continue to be worked on.
+The following commands are currently registered and available in both SSH shell mode and via `SshClient.exec()`. Some flags and edge-case behavior are still being expanded for shell compatibility.
 
 | Command | Purpose | Notes |
 |---------|---------|-------|
-| `pwd` | Print working directory | No args |
+| `adduser <name> <pass>` | Create user | Root only |
+| `cat <path>` | Read file | Displays content |
 | `cd <path>` | Change directory | Updates client cwd |
+| `clear` | Clear screen | No args |
+| `curl <url>` | Fetch URL | Mock implementation |
+| `deluser <name>` | Delete user | Root only, not root |
+| `echo <text...>` | Print text | Supports shell-like argument output |
+| `env` | List environment variables | Shell environment view |
+| `exit [code]` | Close session | Optional exit code |
+| `export NAME=VALUE` | Set/export environment variable | Persists in shell env |
+| `grep <pattern> [path]` | Search for text | Simplified grep behavior |
+| `help` | List commands | No args |
+| `hostname` | Server hostname | No args |
+| `htop` | System monitor | Mock display |
+| `pwd` | Print working directory | No args |
 | `ls [path]` | List directory | Defaults to `.` |
 | `mkdir [-p] <path>` | Create directory | `-p` for parents |
+| `nano <path>` | Text editor | Interactive mode |
+| `neofetch` | Show system summary | Mock display |
 | `touch <path>` | Create empty file | Updates timestamps |
-| `cat <path>` | Read file | Displays content |
 | `rm [-r] <path>` | Remove file/dir | `-r` for recursive |
-| `tree [path]` | ASCII tree view | Defaults to `.` |
-| `whoami` | Current user | No args |
-| `hostname` | Server hostname | No args |
-| `who` | Active sessions | No args |
-| `sudo [-i] <cmd>` | Elevation | Requires sudoer status |
+| `set` | Show shell options/variables | Simplified behavior |
+| `sh <script>` | Run shell script | Simplified execution model |
 | `su <user>` | Switch user | Requires password/sudo |
-| `adduser <name> <pass>` | Create user | Root only |
-| `deluser <name>` | Delete user | Root only, not root |
-| `curl <url>` | Fetch URL | Mock implementation |
+| `sudo [-i] <cmd>` | Elevation | Requires sudoer status |
+| `tree [path]` | ASCII tree view | Defaults to `.` |
+| `unset <name>` | Remove environment variable | Shell environment update |
 | `wget <url>` | Download | Mock implementation |
-| `nano <path>` | Text editor | Interactive mode |
-| `htop` | System monitor | Mock display |
-| `clear` | Clear screen | No args |
-| `exit [code]` | Close session | Optional exit code |
-| `help` | List commands | No args |
+| `who` | Active sessions | No args |
+| `whoami` | Current user | No args |
+
+Commands can be added via the VirtualShell addCommand() method for custom behavior.
 
 ---
 
@@ -1105,10 +1177,11 @@ npm run start
 ### Runtime Options
 
 ```typescript
-const ssh = new VirtualMachine({
+const shell = new VirtualShell("my-container", undefined, "./data");
+const ssh = new VirtualSshServer({
 	port: 2222,                    // Required
 	hostname: "my-container",      // Optional
-	basePath: "./data"             // Optional, default: "."
+	shell                          // Optional, prebuilt shell instance
 });
 ```
 
@@ -1131,8 +1204,9 @@ const ssh = new VirtualMachine({
 **Example:**
 
 ```typescript
-const client1 = new SshClient(ssh, "alice");
-const client2 = new SshClient(ssh, "bob");
+const shell = new VirtualShell("typescript-vm");
+const client1 = new SshClient(shell, "alice");
+const client2 = new SshClient(shell, "bob");
 
 const [result1, result2] = await Promise.all([
 	client1.writeFile("/tmp/alice.txt", "..."),
@@ -1202,7 +1276,7 @@ Error: listen EADDRINUSE :::2222
 **Solution**: Use a different port
 
 ```typescript
-const ssh = new VirtualMachine({ port: 3333 });
+const ssh = new VirtualSshServer({ port: 3333 });
 ```
 
 ### SSH Authentication Failed
@@ -1239,29 +1313,6 @@ await ssh.getVfs().flushMirror();
 
 ---
 
-## Migration Guide
-
-### From v0.0.x to v1.x
-
-Old API:
-
-```typescript
-const ssh = new SshMimic(2222, "hostname");
-```
-
-New API:
-
-```typescript
-const ssh = new VirtualMachine({ port: 2222, hostname: "hostname" });
-```
-
-**Changes**:
-- Object-based constructor
-- Optional `basePath` parameter
-- Exports renamed: `SshMimic` → `VirtualMachine` from main entry
-
----
-
 ## Contributing
 
 1. Fork repository

package/package.json

@@ -3,7 +3,7 @@
   "description": "In-memory SSH server with virtual filesystem and typed programmatic API",
   "module": "src/index.ts",
   "type": "module",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "license": "MIT",
   "keywords": [
     "ssh",

package/src/SSHMimic/client.ts

@@ -1,19 +1,17 @@
 import type { CommandResult } from "../types/commands";
+import type { VirtualShell } from "../VirtualShell";
 import { runCommand } from "../VirtualShell/commands";
-import type { SshMimic } from "./index";
 
 /**
- * Programmatic SSH client to execute shell commands as a specific user.
+ * Programmatic client for executing shell commands against a virtual shell.
  *
- * Maintains connection state (cwd) across multiple command invocations.
- * All commands execute with implicit authentication (no password required).
+ * Maintains working-directory state across invocations and runs commands as a
+ * single authenticated user without SSH transport overhead.
  *
  * @example
  * ```ts
- * const ssh = new SshMimic(2222, "myhost");
- * await ssh.start();
- *
- * const client = new SshClient(ssh, "alice");
+ * const shell = new VirtualShell("typescript-vm");
+ * const client = new SshClient(shell, "alice");
  * const result = await client.cd("/tmp");
  * const list = await client.ls();
  * ```
@@ -22,13 +20,13 @@ export class SshClient {
 	private currentCwd = "/";
 
 	/**
-	 * Creates SSH client bound to user.
+	 * Creates a programmatic client bound to a virtual shell and user.
 	 *
-	 * @param ssh Parent SSH server instance (must be started).
+	 * @param shell Parent virtual shell instance.
 	 * @param username Login user for all commands.
 	 */
 	constructor(
-		private ssh: SshMimic,
+		private shell: VirtualShell,
 		private username: string,
 	) {}
 
@@ -39,9 +37,9 @@ export class SshClient {
 	 * @returns Command result with stdout/stderr/exitCode.
 	 */
 	async exec(command: string): Promise<CommandResult> {
-		const vfs = this.ssh.getVfs();
-		const users = this.ssh.getUsers();
-		const hostname = this.ssh.getHostname();
+		const vfs = this.shell.getVfs();
+		const users = this.shell.getUsers();
+		const hostname = this.shell.getHostname();
 
 		if (!vfs || !users) {
 			throw new Error("SSH client not started");
@@ -51,10 +49,9 @@ export class SshClient {
 			command,
 			this.username,
 			hostname,
-			users,
 			"exec",
 			this.currentCwd,
-			vfs,
+			this.shell,
 		);
 
 		// Handle async results
@@ -151,7 +148,7 @@ export class SshClient {
 	 * @returns Result from touch/write simulation.
 	 */
 	async writeFile(path: string, content: string): Promise<CommandResult> {
-		const vfs = this.ssh.getVfs();
+		const vfs = this.shell.getVfs();
 		if (!vfs) {
 			throw new Error("SSH client not started");
 		}
@@ -174,7 +171,7 @@ export class SshClient {
 	 * @returns File content as string or error in result.
 	 */
 	async readFile(path: string): Promise<CommandResult> {
-		const vfs = this.ssh.getVfs();
+		const vfs = this.shell.getVfs();
 		if (!vfs) {
 			throw new Error("SSH client not started");
 		}

package/src/SSHMimic/exec.ts

@@ -1,8 +1,6 @@
 import type { ExecStream } from "../types/streams";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import { defaultShellProperties } from "../VirtualShell";
+import type { VirtualShell } from "../VirtualShell";
 import { runCommand } from "../VirtualShell/commands";
-import type { VirtualUserManager } from "./users";
 
 function toTtyLines(text: string): string {
 	return text
@@ -16,20 +14,10 @@ export function runExec(
 	cmd: string,
 	authUser: string,
 	hostname: string,
-	users: VirtualUserManager,
-	vfs: VirtualFileSystem,
+	shell: VirtualShell,
 ): void {
 	Promise.resolve(
-		runCommand(
-			cmd,
-			authUser,
-			hostname,
-			users,
-			"exec",
-			`/home/${authUser}`,
-			defaultShellProperties,
-			vfs,
-		),
+		runCommand(cmd, authUser, hostname, "exec", `/home/${authUser}`, shell),
 	).then((result) => {
 		if (result.stdout) {
 			stream.write(`${toTtyLines(result.stdout)}\r\n`);
@@ -40,7 +28,8 @@ export function runExec(
 		}
 
 		stream.exit(result.exitCode ?? 0);
-		void vfs.flushMirror();
+		console.log(shell.vfs);
+		void shell.vfs.flushMirror();
 		stream.end();
 	});
 }