typescript-virtual-container 0.1.0

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are prioritized for the latest published release.
+
+## Reporting a Vulnerability
+
+Please report vulnerabilities privately.
+
+Preferred channel:
+
+- Open a private GitHub security advisory for this repository.
+
+If advisory tooling is unavailable, open an issue with minimal details and request private contact.
+Do not include exploit details or sensitive information in a public issue.
+
+## What to Include
+
+Please include:
+
+- A clear description of the issue
+- Impact assessment
+- Reproduction steps or proof of concept
+- Affected versions
+- Suggested remediation if available
+
+## Disclosure Process
+
+- We will acknowledge receipt as soon as possible.
+- We will validate, triage, and work on a fix.
+- We may request additional technical details.
+- We will publish a patch and release notes after remediation.

package/biome.json

@@ -0,0 +1,20 @@
+{
+    "linter": {
+        "rules": {
+            "suspicious": {
+                "noDebugger": "off"
+            },
+            "style": {
+                "noShoutyConstants": "warn",
+                "useNamingConvention": "error",
+                "noNonNullAssertion": "off"
+            }
+        }
+    },
+    "assist": {
+        "source": {
+            "autoImport": "on",
+            "importModuleSpecifierPreference": "relative"
+        }
+    }
+}

package/bun.lock

@@ -0,0 +1,99 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "virtual-env-js",
+      "dependencies": {
+        "ssh2": "^1.17.0",
+        "tar-stream": "^3.1.8",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "^2.4.11",
+        "@types/bun": "latest",
+        "@types/node": "^25.6.0",
+        "@types/ssh2": "^1.15.5",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.11", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.11", "@biomejs/cli-darwin-x64": "2.4.11", "@biomejs/cli-linux-arm64": "2.4.11", "@biomejs/cli-linux-arm64-musl": "2.4.11", "@biomejs/cli-linux-x64": "2.4.11", "@biomejs/cli-linux-x64-musl": "2.4.11", "@biomejs/cli-win32-arm64": "2.4.11", "@biomejs/cli-win32-x64": "2.4.11" }, "bin": { "biome": "bin/biome" } }, "sha512-nWxHX8tf3Opb/qRgZpBbsTOqOodkbrkJ7S+JxJAruxOReaDPPmPuLBAGQ8vigyUgo0QBB+oQltNEAvalLcjggA=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.11", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wOt+ed+L2dgZanWyL6i29qlXMc088N11optzpo10peayObBaAshbTcxKUchzEMp9QSY8rh5h6VfAFE3WTS1rqg=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.11", "", { "os": "darwin", "cpu": "x64" }, "sha512-gZ6zR8XmZlExfi/Pz/PffmdpWOQ8Qhy7oBztgkR8/ylSRyLwfRPSadmiVCV8WQ8PoJ2MWUy2fgID9zmtgUUJmw=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-avdJaEElXrKceK0va9FkJ4P5ci3N01TGkc6ni3P8l3BElqbOz42Wg2IyX3gbh0ZLEd4HVKEIrmuVu/AMuSeFFA=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-+Sbo1OAmlegtdwqFE8iOxFIWLh1B3OEgsuZfBpyyN/kWuqZ8dx9ZEes6zVnDMo+zRHF2wLynRVhoQmV7ohxl2Q=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.11", "", { "os": "linux", "cpu": "x64" }, "sha512-TagWV0iomp5LnEnxWFg4nQO+e52Fow349vaX0Q/PIcX6Zhk4GGBgp3qqZ8PVkpC+cuehRctMf3+6+FgQ8jCEFQ=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.11", "", { "os": "linux", "cpu": "x64" }, "sha512-bexd2IklK7ZgPhrz6jXzpIL6dEAH9MlJU1xGTrypx+FICxrXUp4CqtwfiuoDKse+UlgAlWtzML3jrMqeEAHEhA=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.11", "", { "os": "win32", "cpu": "arm64" }, "sha512-RJhaTnY8byzxDt4bDVb7AFPHkPcjOPK3xBip4ZRTrN3TEfyhjLRm3r3mqknqydgVTB74XG8l4jMLwEACEeihVg=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.11", "", { "os": "win32", "cpu": "x64" }, "sha512-A8D3JM/00C2KQgUV3oj8Ba15EHEYwebAGCy5Sf9GAjr5Y3+kJIYOiESoqRDeuRZueuMdCsbLZIUqmPhpYXJE9A=="],
+
+    "@types/bun": ["@types/bun@1.3.12", "", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "@types/ssh2": ["@types/ssh2@1.15.5", "", { "dependencies": { "@types/node": "^18.11.18" } }, "sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ=="],
+
+    "asn1": ["asn1@0.2.6", "", { "dependencies": { "safer-buffer": "~2.1.0" } }, "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ=="],
+
+    "b4a": ["b4a@1.8.0", "", { "peerDependencies": { "react-native-b4a": "*" }, "optionalPeers": ["react-native-b4a"] }, "sha512-qRuSmNSkGQaHwNbM7J78Wwy+ghLEYF1zNrSeMxj4Kgw6y33O3mXcQ6Ie9fRvfU/YnxWkOchPXbaLb73TkIsfdg=="],
+
+    "bare-events": ["bare-events@2.8.2", "", { "peerDependencies": { "bare-abort-controller": "*" }, "optionalPeers": ["bare-abort-controller"] }, "sha512-riJjyv1/mHLIPX4RwiK+oW9/4c3TEUeORHKefKAKnZ5kyslbN+HXowtbaVEqt4IMUB7OXlfixcs6gsFeo/jhiQ=="],
+
+    "bare-fs": ["bare-fs@4.7.0", "", { "dependencies": { "bare-events": "^2.5.4", "bare-path": "^3.0.0", "bare-stream": "^2.6.4", "bare-url": "^2.2.2", "fast-fifo": "^1.3.2" }, "peerDependencies": { "bare-buffer": "*" }, "optionalPeers": ["bare-buffer"] }, "sha512-xzqKsCFxAek9aezYhjJuJRXBIaYlg/0OGDTZp+T8eYmYMlm66cs6cYko02drIyjN2CBbi+I6L7YfXyqpqtKRXA=="],
+
+    "bare-os": ["bare-os@3.8.7", "", {}, "sha512-G4Gr1UsGeEy2qtDTZwL7JFLo2wapUarz7iTMcYcMFdS89AIQuBoyjgXZz0Utv7uHs3xA9LckhVbeBi8lEQrC+w=="],
+
+    "bare-path": ["bare-path@3.0.0", "", { "dependencies": { "bare-os": "^3.0.1" } }, "sha512-tyfW2cQcB5NN8Saijrhqn0Zh7AnFNsnczRcuWODH0eYAXBsJ5gVxAUuNr7tsHSC6IZ77cA0SitzT+s47kot8Mw=="],
+
+    "bare-stream": ["bare-stream@2.13.0", "", { "dependencies": { "streamx": "^2.25.0", "teex": "^1.0.1" }, "peerDependencies": { "bare-abort-controller": "*", "bare-buffer": "*", "bare-events": "*" }, "optionalPeers": ["bare-abort-controller", "bare-buffer", "bare-events"] }, "sha512-3zAJRZMDFGjdn+RVnNpF9kuELw+0Fl3lpndM4NcEOhb9zwtSo/deETfuIwMSE5BXanA0FrN1qVjffGwAg2Y7EA=="],
+
+    "bare-url": ["bare-url@2.4.0", "", { "dependencies": { "bare-path": "^3.0.0" } }, "sha512-NSTU5WN+fy/L0DDenfE8SXQna4voXuW0FHM7wH8i3/q9khUSchfPbPezO4zSFMnDGIf9YE+mt/RWhZgNRKRIXA=="],
+
+    "bcrypt-pbkdf": ["bcrypt-pbkdf@1.0.2", "", { "dependencies": { "tweetnacl": "^0.14.3" } }, "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w=="],
+
+    "buildcheck": ["buildcheck@0.0.7", "", {}, "sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA=="],
+
+    "bun-types": ["bun-types@1.3.12", "", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
+
+    "cpu-features": ["cpu-features@0.0.10", "", { "dependencies": { "buildcheck": "~0.0.6", "nan": "^2.19.0" } }, "sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA=="],
+
+    "events-universal": ["events-universal@1.0.1", "", { "dependencies": { "bare-events": "^2.7.0" } }, "sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw=="],
+
+    "fast-fifo": ["fast-fifo@1.3.2", "", {}, "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ=="],
+
+    "nan": ["nan@2.26.2", "", {}, "sha512-0tTvBTYkt3tdGw22nrAy50x7gpbGCCFH3AFcyS5WiUu7Eu4vWlri1woE6qHBSfy11vksDqkiwjOnlR7WV8G1Hw=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "ssh2": ["ssh2@1.17.0", "", { "dependencies": { "asn1": "^0.2.6", "bcrypt-pbkdf": "^1.0.2" }, "optionalDependencies": { "cpu-features": "~0.0.10", "nan": "^2.23.0" } }, "sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ=="],
+
+    "streamx": ["streamx@2.25.0", "", { "dependencies": { "events-universal": "^1.0.0", "fast-fifo": "^1.3.2", "text-decoder": "^1.1.0" } }, "sha512-0nQuG6jf1w+wddNEEXCF4nTg3LtufWINB5eFEN+5TNZW7KWJp6x87+JFL43vaAUPyCfH1wID+mNVyW6OHtFamg=="],
+
+    "tar-stream": ["tar-stream@3.1.8", "", { "dependencies": { "b4a": "^1.6.4", "bare-fs": "^4.5.5", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ=="],
+
+    "teex": ["teex@1.0.1", "", { "dependencies": { "streamx": "^2.12.5" } }, "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg=="],
+
+    "text-decoder": ["text-decoder@1.2.7", "", { "dependencies": { "b4a": "^1.6.4" } }, "sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ=="],
+
+    "tweetnacl": ["tweetnacl@0.14.5", "", {}, "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+
+    "@types/ssh2/@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
+
+    "@types/ssh2/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "typescript-virtual-container",
+  "description": "In-memory SSH server with virtual filesystem and typed programmatic API",
+  "module": "src/index.ts",
+  "type": "module",
+  "version": "0.1.0",
+  "license": "MIT",
+  "keywords": [
+    "ssh",
+    "virtual-filesystem",
+    "typescript",
+    "testing",
+    "automation",
+    "shell"
+  ],
+  "scripts": {
+    "postinstall": "rm -f node_modules/ssh2/lib/protocol/crypto/build/Release/sshcrypto.node && rm -rf node_modules/cpu-features",
+    "format": "bunx --bun @biomejs/biome format --write ./src",
+    "check": "bunx --bun @biomejs/biome check ./src",
+    "lint": "bunx --bun @biomejs/biome lint ./src",
+    "lint:write": "bunx --bun @biomejs/biome lint --write ./src",
+    "test": "bunx --bun @biomejs/biome test ./src",
+    "deploy:npm": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.11",
+    "@types/bun": "latest",
+    "@types/node": "^25.6.0",
+    "@types/ssh2": "^1.15.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "ssh2": "^1.17.0",
+    "tar-stream": "^3.1.8"
+  }
+}

package/src/SSHMimic/client.ts

@@ -0,0 +1,248 @@
+import type { CommandResult } from "../types/commands";
+import { runCommand } from "./commands";
+import type { SshMimic } from "./index";
+
+/**
+ * Programmatic SSH client to execute shell commands as a specific user.
+ *
+ * Maintains connection state (cwd) across multiple command invocations.
+ * All commands execute with implicit authentication (no password required).
+ *
+ * @example
+ * ```ts
+ * const ssh = new SshMimic(2222, "myhost");
+ * await ssh.start();
+ *
+ * const client = new SshClient(ssh, "alice");
+ * const result = await client.cd("/tmp");
+ * const list = await client.ls();
+ * ```
+ */
+export class SshClient {
+	private currentCwd = "/";
+
+	/**
+	 * Creates SSH client bound to user.
+	 *
+	 * @param ssh Parent SSH server instance (must be started).
+	 * @param username Login user for all commands.
+	 */
+	constructor(
+		private ssh: SshMimic,
+		private username: string,
+	) {}
+
+	/**
+	 * Executes raw shell command.
+	 *
+	 * @param command Unparsed command line.
+	 * @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();
+
+		if (!vfs || !users) {
+			throw new Error("SSH client not started");
+		}
+
+		const result = runCommand(
+			command,
+			this.username,
+			hostname,
+			users,
+			"exec",
+			this.currentCwd,
+			vfs,
+		);
+
+		// Handle async results
+		if (result instanceof Promise) {
+			return await result;
+		}
+
+		return result;
+	}
+
+	/**
+	 * Lists directory contents.
+	 *
+	 * @param path Target directory, defaults to cwd.
+	 * @returns Result with directory listing in stdout.
+	 */
+	async ls(path?: string): Promise<CommandResult> {
+		const target = path ?? ".";
+		return this.exec(`ls ${target}`);
+	}
+
+	/**
+	 * Prints current working directory.
+	 *
+	 * @returns Result with cwd path in stdout.
+	 */
+	async pwd(): Promise<CommandResult> {
+		return this.exec("pwd");
+	}
+
+	/**
+	 * Changes working directory.
+	 *
+	 * @param path Target directory path.
+	 * @returns Result; updates internal cwd on success.
+	 */
+	async cd(path: string): Promise<CommandResult> {
+		const result = await this.exec(`cd ${path}`);
+		if (result.nextCwd && result.exitCode !== 1) {
+			this.currentCwd = result.nextCwd;
+		}
+		return result;
+	}
+
+	/**
+	 * Reads file content.
+	 *
+	 * @param path File path.
+	 * @returns Result with file content in stdout.
+	 */
+	async cat(path: string): Promise<CommandResult> {
+		return this.exec(`cat ${path}`);
+	}
+
+	/**
+	 * Creates directory.
+	 *
+	 * @param path Directory path.
+	 * @param recursive When true, create parents.
+	 * @returns Result from mkdir command.
+	 */
+	async mkdir(path: string, recursive = false): Promise<CommandResult> {
+		const flag = recursive ? "-p " : "";
+		return this.exec(`mkdir ${flag}${path}`);
+	}
+
+	/**
+	 * Creates file (empty).
+	 *
+	 * @param path File path.
+	 * @returns Result from touch command.
+	 */
+	async touch(path: string): Promise<CommandResult> {
+		return this.exec(`touch ${path}`);
+	}
+
+	/**
+	 * Removes file or directory.
+	 *
+	 * @param path Target path.
+	 * @param recursive When true, delete directory tree.
+	 * @returns Result from rm command.
+	 */
+	async rm(path: string, recursive = false): Promise<CommandResult> {
+		const flag = recursive ? "-r " : "";
+		return this.exec(`rm ${flag}${path}`);
+	}
+
+	/**
+	 * Writes file content.
+	 *
+	 * @param path Target file path.
+	 * @param content Text to write.
+	 * @returns Result from touch/write simulation.
+	 */
+	async writeFile(path: string, content: string): Promise<CommandResult> {
+		const vfs = this.ssh.getVfs();
+		if (!vfs) {
+			throw new Error("SSH client not started");
+		}
+
+		try {
+			vfs.writeFile(path, content);
+			return { stdout: `File '${path}' written`, exitCode: 0 };
+		} catch (error) {
+			return {
+				stderr: `Failed to write '${path}': ${error instanceof Error ? error.message : String(error)}`,
+				exitCode: 1,
+			};
+		}
+	}
+
+	/**
+	 * Reads file content programmatically.
+	 *
+	 * @param path Target file path.
+	 * @returns File content as string or error in result.
+	 */
+	async readFile(path: string): Promise<CommandResult> {
+		const vfs = this.ssh.getVfs();
+		if (!vfs) {
+			throw new Error("SSH client not started");
+		}
+
+		try {
+			const content = vfs.readFile(path);
+			return { stdout: content, exitCode: 0 };
+		} catch (error) {
+			return {
+				stderr: `Failed to read '${path}': ${error instanceof Error ? error.message : String(error)}`,
+				exitCode: 1,
+			};
+		}
+	}
+
+	/**
+	 * Gets current working directory.
+	 *
+	 * @returns Normalized cwd path.
+	 */
+	getCwd(): string {
+		return this.currentCwd;
+	}
+
+	/**
+	 * Gets logged-in username.
+	 *
+	 * @returns Associated username.
+	 */
+	getUsername(): string {
+		return this.username;
+	}
+
+	/**
+	 * Renders tree view of directory.
+	 *
+	 * @param path Target directory, defaults to cwd.
+	 * @returns Result with ASCII tree in stdout.
+	 */
+	async tree(path?: string): Promise<CommandResult> {
+		const target = path ?? ".";
+		return this.exec(`tree ${target}`);
+	}
+
+	/**
+	 * Shows current user.
+	 *
+	 * @returns Result from whoami command.
+	 */
+	async whoami(): Promise<CommandResult> {
+		return this.exec("whoami");
+	}
+
+	/**
+	 * Shows hostname.
+	 *
+	 * @returns Result from hostname command.
+	 */
+	async hostname(): Promise<CommandResult> {
+		return this.exec("hostname");
+	}
+
+	/**
+	 * Lists active users/sessions.
+	 *
+	 * @returns Result from who command.
+	 */
+	async who(): Promise<CommandResult> {
+		return this.exec("who");
+	}
+}

package/src/SSHMimic/commands/adduser.ts

@@ -0,0 +1,22 @@
+import type { ShellModule } from "../../types/commands";
+
+export const adduserCommand: ShellModule = {
+	name: "adduser",
+	params: ["<username> <password>"],
+	run: async ({ authUser, users, args }) => {
+		if (authUser !== "root") {
+			return { stderr: "adduser: permission denied", exitCode: 1 };
+		}
+
+		const [username, password] = args;
+		if (!username || !password) {
+			return {
+				stderr: "adduser: usage: adduser <username> <password>",
+				exitCode: 1,
+			};
+		}
+
+		await users.addUser(username, password);
+		return { stdout: `adduser: user '${username}' created`, exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/cat.ts

@@ -0,0 +1,16 @@
+import type { ShellModule } from "../../types/commands";
+import { resolveReadablePath } from "./helpers";
+
+export const catCommand: ShellModule = {
+	name: "cat",
+	params: ["<file>"],
+	run: ({ vfs, cwd, args }) => {
+		const fileArg = args[0];
+		if (!fileArg) {
+			return { stderr: "cat: missing file operand", exitCode: 1 };
+		}
+
+		const target = resolveReadablePath(vfs, cwd, fileArg);
+		return { stdout: vfs.readFile(target), exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/cd.ts

@@ -0,0 +1,20 @@
+import type { ShellModule } from "../../types/commands";
+import { resolvePath } from "./helpers";
+
+export const cdCommand: ShellModule = {
+	name: "cd",
+	params: ["[path]"],
+	run: ({ vfs, cwd, args, mode }) => {
+		const target = resolvePath(cwd, args[0] ?? "/virtual-env-js");
+		const stats = vfs.stat(target);
+		if (stats.type !== "directory") {
+			return { stderr: `cd: not a directory: ${target}`, exitCode: 1 };
+		}
+
+		if (mode === "exec") {
+			return { exitCode: 0 };
+		}
+
+		return { nextCwd: target, exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/clear.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../../types/commands";
+
+export const clearCommand: ShellModule = {
+	name: "clear",
+	params: [],
+	run: () => ({ clearScreen: true, exitCode: 0 }),
+};

package/src/SSHMimic/commands/curl.ts

@@ -0,0 +1,27 @@
+import type { ShellModule } from "../../types/commands";
+import { fetchResource, parseOutputPath, resolvePath } from "./helpers";
+
+export const curlCommand: ShellModule = {
+	name: "curl",
+	params: ["[-o file] <url>"],
+	run: async ({ vfs, cwd, args }) => {
+		const { outputPath, inputArgs } = parseOutputPath(args);
+		const url = inputArgs[0];
+
+		if (!url) {
+			return { stderr: "curl: missing URL", exitCode: 1 };
+		}
+
+		const result = await fetchResource(url);
+		if (result.status >= 400) {
+			return { stderr: `curl: HTTP ${result.status}`, exitCode: 22 };
+		}
+
+		if (outputPath) {
+			vfs.writeFile(resolvePath(cwd, outputPath), result.text);
+			return { exitCode: 0 };
+		}
+
+		return { stdout: result.text, exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/deluser.ts

@@ -0,0 +1,19 @@
+import type { ShellModule } from "../../types/commands";
+
+export const deluserCommand: ShellModule = {
+	name: "deluser",
+	params: ["<username>"],
+	run: async ({ authUser, users, args }) => {
+		if (authUser !== "root") {
+			return { stderr: "deluser: permission denied", exitCode: 1 };
+		}
+
+		const [username] = args;
+		if (!username) {
+			return { stderr: "deluser: usage: deluser <username>", exitCode: 1 };
+		}
+
+		await users.deleteUser(username);
+		return { stdout: `deluser: user '${username}' deleted`, exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/exit.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../../types/commands";
+
+export const exitCommand: ShellModule = {
+	name: "exit",
+	params: [],
+	run: () => ({ closeSession: true, exitCode: 0 }),
+};

package/src/SSHMimic/commands/help.ts

@@ -0,0 +1,9 @@
+import type { ShellModule } from "../../types/commands";
+
+export function createHelpCommand(getNames: () => string[]): ShellModule {
+	return {
+		name: "help",
+		params: [],
+		run: () => ({ stdout: `Builtins: ${getNames().join(" ")}`, exitCode: 0 }),
+	};
+}