typescript-virtual-container 1.0.7 → 1.1.0

package/src/SSHMimic/executor.ts

@@ -1,10 +1,8 @@
 import type { CommandMode, CommandResult } from "../types/commands";
 import type { Pipeline, PipelineCommand } from "../types/pipeline";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import { defaultShellProperties } from "../VirtualShell";
+import type { VirtualShell } from "../VirtualShell";
 import { runCommand as runSingleCommand } from "../VirtualShell/commands";
 import { resolvePath } from "../VirtualShell/commands/helpers";
-import type { VirtualUserManager } from "./users";
 
 /**
  * Execute a parsed pipeline, chaining commands and handling redirections.
@@ -14,10 +12,9 @@ export async function executePipeline(
 	pipeline: Pipeline,
 	authUser: string,
 	hostname: string,
-	users: VirtualUserManager,
 	mode: CommandMode,
 	cwd: string,
-	vfs: VirtualFileSystem,
+	shell: VirtualShell,
 ): Promise<CommandResult> {
 	if (pipeline.commands.length === 0) {
 		return { exitCode: 0 };
@@ -29,10 +26,9 @@ export async function executePipeline(
 			pipeline.commands[0] as PipelineCommand,
 			authUser,
 			hostname,
-			users,
 			mode,
 			cwd,
-			vfs,
+			shell,
 		);
 	}
 
@@ -41,10 +37,9 @@ export async function executePipeline(
 		pipeline.commands as PipelineCommand[],
 		authUser,
 		hostname,
-		users,
 		mode,
 		cwd,
-		vfs,
+		shell,
 	);
 }
 
@@ -55,17 +50,16 @@ async function executeSingleCommandWithRedirections(
 	cmd: PipelineCommand,
 	authUser: string,
 	hostname: string,
-	users: VirtualUserManager,
 	mode: CommandMode,
 	cwd: string,
-	vfs: VirtualFileSystem,
+	shell: VirtualShell,
 ): Promise<CommandResult> {
 	// Prepare input if input file specified
 	let stdin: string | undefined;
 	if (cmd.inputFile) {
 		const inputPath = resolvePath(cwd, cmd.inputFile);
 		try {
-			stdin = vfs.readFile(inputPath);
+			stdin = shell.vfs.readFile(inputPath);
 		} catch {
 			return {
 				stderr: `cat: ${cmd.inputFile}: No such file or directory`,
@@ -82,11 +76,9 @@ async function executeSingleCommandWithRedirections(
 		rawInput,
 		authUser,
 		hostname,
-		users,
 		mode,
 		cwd,
-		defaultShellProperties,
-		vfs,
+		shell,
 		stdin,
 	);
 
@@ -97,13 +89,13 @@ async function executeSingleCommandWithRedirections(
 		try {
 			if (cmd.appendOutput) {
 				try {
-					const existing = vfs.readFile(outputPath);
-					vfs.writeFile(outputPath, existing + output);
+					const existing = shell.vfs.readFile(outputPath);
+					shell.vfs.writeFile(outputPath, existing + output);
 				} catch {
-					vfs.writeFile(outputPath, output);
+					shell.vfs.writeFile(outputPath, output);
 				}
 			} else {
-				vfs.writeFile(outputPath, output);
+				shell.vfs.writeFile(outputPath, output);
 			}
 			return { ...result, stdout: "" };
 		} catch {
@@ -125,10 +117,9 @@ async function executePipelineChain(
 	commands: PipelineCommand[],
 	authUser: string,
 	hostname: string,
-	users: VirtualUserManager,
 	mode: CommandMode,
 	cwd: string,
-	vfs: VirtualFileSystem,
+	shell: VirtualShell,
 ): Promise<CommandResult> {
 	let currentOutput = "";
 	let exitCode = 0;
@@ -140,7 +131,7 @@ async function executePipelineChain(
 		if (i === 0 && cmd.inputFile) {
 			const inputPath = resolvePath(cwd, cmd.inputFile);
 			try {
-				currentOutput = vfs.readFile(inputPath);
+				currentOutput = shell.vfs.readFile(inputPath);
 			} catch {
 				return {
 					stderr: `cat: ${cmd.inputFile}: No such file or directory`,
@@ -158,11 +149,9 @@ async function executePipelineChain(
 			rawInput,
 			authUser,
 			hostname,
-			users,
 			mode,
 			cwd,
-			defaultShellProperties,
-			vfs,
+			shell,
 			currentOutput,
 		);
 
@@ -175,13 +164,13 @@ async function executePipelineChain(
 			try {
 				if (cmd.appendOutput) {
 					try {
-						const existing = vfs.readFile(outputPath);
-						vfs.writeFile(outputPath, existing + output);
+						const existing = shell.vfs.readFile(outputPath);
+						shell.vfs.writeFile(outputPath, existing + output);
 					} catch {
-						vfs.writeFile(outputPath, output);
+						shell.vfs.writeFile(outputPath, output);
 					}
 				} else {
-					vfs.writeFile(outputPath, output);
+					shell.vfs.writeFile(outputPath, output);
 				}
 				currentOutput = "";
 			} catch {

package/src/SSHMimic/index.ts

@@ -1,67 +1,40 @@
-import { randomBytes } from "node:crypto";
 import { Server as SshServer } from "ssh2";
-import VirtualFileSystem from "../VirtualFileSystem";
 import { VirtualShell } from "../VirtualShell";
 import { loadOrCreateHostKey } from "./hostKey";
-import { VirtualUserManager } from "./users";
-
-function resolveRootPassword(): string {
-	const configured = process.env.SSH_MIMIC_ROOT_PASSWORD;
-	if (configured && configured.trim().length > 0) {
-		return configured;
-	}
-
-	const generated = randomBytes(18).toString("base64url");
-	console.warn(
-		`[ssh-mimic] SSH_MIMIC_ROOT_PASSWORD missing; generated ephemeral root password: ${generated}`,
-	);
-	return generated;
-}
-
-function resolveAutoSudoForNewUsers(): boolean {
-	const configured = process.env.SSH_MIMIC_AUTO_SUDO_NEW_USERS;
-	if (!configured) {
-		return true;
-	}
-
-	return !["0", "false", "no", "off"].includes(configured.toLowerCase());
-}
 
 /**
- * SSH server wrapper that exposes virtual shell and exec sessions.
+ * SSH server facade that wires the virtual shell runtime into ssh2 sessions.
  *
+ * This class is exported as `VirtualSshServer` for public API compatibility.
  * Create an instance, call {@link SshMimic.start}, and stop it with
  * {@link SshMimic.stop} when your process exits.
  */
 class SshMimic {
 	port: number;
-	hostname: string;
 	server: SshServer | null;
-	vfs: VirtualFileSystem | null = null;
-	users: VirtualUserManager | null = null;
-	shell: VirtualShell | null = null;
-	basePath: string = ".";
+	private shell: VirtualShell;
+	private shellHostname: string;
 
 	/**
 	 * Creates a new SSH mimic server instance.
 	 *
 	 * @param port TCP port to bind on localhost.
-	 * @param hostname SSH ident hostname suffix and virtual host label.
-	 * @param basePath Optional base path for virtual filesystem (default: current directory).
+	 * @param hostname Virtual hostname used for the SSH ident and default shell label.
+	 * @param shell Optional preconfigured virtual shell instance to reuse.
 	 */
 	constructor({
 		port,
 		hostname = "typescript-vm",
-		basePath = ".",
+		shell = new VirtualShell(hostname),
 	}: {
 		port: number;
 		hostname?: string;
-		basePath?: string;
+		shell?: VirtualShell;
 	}) {
 		this.port = port;
-		this.hostname = hostname;
-		this.basePath = basePath;
+		this.shellHostname = hostname;
 		this.server = null;
+		this.shell = shell;
 	}
 
 	/**
@@ -70,22 +43,13 @@ class SshMimic {
 	 * @returns Promise resolved with bound listening port.
 	 */
 	public async start(): Promise<number> {
+		const shell = this.shell;
 		const privateKey = loadOrCreateHostKey();
-		this.vfs = new VirtualFileSystem(this.basePath);
-		await this.vfs.restoreMirror();
-		this.users = new VirtualUserManager(
-			this.vfs,
-			resolveRootPassword(),
-			resolveAutoSudoForNewUsers(),
-		);
-		await this.users.initialize();
-
-		this.shell = new VirtualShell(this.vfs, this.users, this.hostname);
 
 		this.server = new SshServer(
 			{
 				hostKeys: [privateKey],
-				ident: `SSH-2.0-${this.hostname}`,
+				ident: `SSH-2.0-${shell.hostname}`,
 			},
 			(client) => {
 				let authUser = "root";
@@ -93,28 +57,29 @@ class SshMimic {
 				let sessionId: string | null = null;
 
 				client.on("authentication", (ctx) => {
+					shell;
 					if (ctx.method === "password") {
 						const candidateUser = ctx.username || "root";
 						remoteAddress = (ctx as { ip?: string }).ip ?? remoteAddress;
 
 						if (
-							!this.users!.verifyPassword(candidateUser, ctx.password ?? "")
+							!shell.users.verifyPassword(candidateUser, ctx.password ?? "")
 						) {
 							ctx.reject();
 							return;
 						}
 
 						authUser = candidateUser;
-						sessionId = this.users!.registerSession(authUser, remoteAddress).id;
+						sessionId = shell.users.registerSession(authUser, remoteAddress).id;
 
 						const homePath = `/home/${authUser}`;
-						if (!this.vfs!.exists(homePath)) {
-							this.vfs!.mkdir(homePath, 0o755);
-							this.vfs!.writeFile(
+						if (!shell.vfs.exists(homePath)) {
+							shell.vfs.mkdir(homePath, 0o755);
+							shell.vfs.writeFile(
 								`${homePath}/README.txt`,
-								`Welcome to ${this.hostname}`,
+								`Welcome to ${shell?.hostname ?? this.shellHostname}`,
 							);
-							void this.vfs!.flushMirror();
+							void shell.vfs.flushMirror();
 						}
 
 						ctx.accept();
@@ -125,7 +90,7 @@ class SshMimic {
 				});
 
 				client.on("close", () => {
-					this.users!.unregisterSession(sessionId);
+					shell.users.unregisterSession(sessionId);
 					sessionId = null;
 				});
 
@@ -150,7 +115,7 @@ class SshMimic {
 
 						session.on("shell", (acceptShell) => {
 							const stream = acceptShell();
-							this.shell?.startInteractiveSession(
+							shell?.startInteractiveSession(
 								stream,
 								authUser,
 								sessionId,
@@ -161,7 +126,7 @@ class SshMimic {
 
 						session.on("exec", (acceptExec, _rejectExec, info) => {
 							const _stream = acceptExec();
-							this.shell?.executeCommand(
+							shell?.executeCommand(
 								info.command.trim(),
 								authUser,
 								`/home/${authUser}`,
@@ -191,33 +156,6 @@ class SshMimic {
 			});
 		}
 	}
-
-	/**
-	 * Returns virtual filesystem instance after server started.
-	 *
-	 * @returns VirtualFileSystem or null when not started.
-	 */
-	public getVfs(): VirtualFileSystem | null {
-		return this.vfs;
-	}
-
-	/**
-	 * Returns user manager instance after server started.
-	 *
-	 * @returns VirtualUserManager or null when not started.
-	 */
-	public getUsers(): VirtualUserManager | null {
-		return this.users;
-	}
-
-	/**
-	 * Returns hostname shown in prompts and idents.
-	 *
-	 * @returns Configured hostname label.
-	 */
-	public getHostname(): string {
-		return this.hostname;
-	}
 }
 
 export { SshMimic };

package/src/VirtualFileSystem/index.ts

@@ -49,7 +49,6 @@ class VirtualFileSystem {
 	 */
 	public async restoreMirror(): Promise<void> {
 		await fs.mkdir(path.dirname(this.archivePath), { recursive: true });
-
 		try {
 			const compressed = await fs.readFile(this.archivePath);
 			const tarBuffer = gunzipSync(compressed);
@@ -58,6 +57,9 @@ class VirtualFileSystem {
 			this.dirty = false;
 			return;
 		} catch {
+			console.warn(
+				`No valid mirror archive found at '${this.archivePath}'. Starting with empty filesystem.`,
+			);
 			await this.flushMirror();
 		}
 	}

package/src/VirtualShell/commands/adduser.ts

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

package/src/VirtualShell/commands/cat.ts

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

package/src/VirtualShell/commands/cd.ts

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

package/src/VirtualShell/commands/command-helpers.ts

@@ -133,3 +133,67 @@ export function getArg(
 	const positionals = collectPositionals(args, options);
 	return positionals[index];
 }
+
+/**
+ * Parse arguments into flags, flags with values, and positionals.
+ * @param args - Array of arguments to parse.
+ * @param options - Parsing options for flags and flags with values.
+ * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ */
+export function parseArgs(
+	args: string[],
+	options: { flags?: string[]; flagsWithValue?: string[] } = {},
+): {
+	flags: Set<string>;
+	flagsWithValues: Map<string, string>;
+	positionals: string[];
+} {
+	const flags = new Set<string>();
+	const flagsWithValues = new Map<string, string>();
+	const positionals: string[] = [];
+	const boolFlags = new Set(options.flags ?? []);
+	const valueFlags = new Set(options.flagsWithValue ?? []);
+	let passthrough = false;
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index]!;
+
+		if (passthrough) {
+			positionals.push(arg);
+			continue;
+		}
+
+		if (arg === "--") {
+			passthrough = true;
+			continue;
+		}
+
+		if (boolFlags.has(arg)) {
+			flags.add(arg);
+			continue;
+		}
+
+		if (valueFlags.has(arg)) {
+			const next = args[index + 1];
+			if (next && !next.startsWith("-")) {
+				flagsWithValues.set(arg, next);
+				index += 1;
+			} else {
+				flagsWithValues.set(arg, "");
+			}
+			continue;
+		}
+
+		const inlineFlag = Array.from(valueFlags).find((flag) =>
+			arg.startsWith(`${flag}=`),
+		);
+		if (inlineFlag) {
+			flagsWithValues.set(inlineFlag, arg.slice(inlineFlag.length + 1));
+			continue;
+		}
+
+		positionals.push(arg);
+	}
+
+	return { flags, flagsWithValues, positionals };
+}

package/src/VirtualShell/commands/curl.ts

@@ -1,107 +1,31 @@
-import { spawn } from "node:child_process";
 import type { ShellModule } from "../../types/commands";
-import { getArg, getFlag, ifFlag } from "./command-helpers";
+import { parseArgs } from "./command-helpers";
 import {
 	assertPathAccess,
 	normalizeTerminalOutput,
 	resolvePath,
+	runHostCommand,
 } from "./helpers";
 
-function runHostCurl(args: string[]): Promise<{
-	stdout: string;
-	stderr: string;
-	exitCode: number;
-}> {
-	return new Promise((resolve) => {
-		let childProcess: ReturnType<typeof spawn>;
-
-		try {
-			childProcess = spawn("curl", args, {
-				stdio: ["ignore", "pipe", "pipe"],
-			});
-		} catch (error) {
-			resolve({
-				stdout: "",
-				stderr: `curl: ${error instanceof Error ? error.message : String(error)}`,
-				exitCode: 1,
-			});
-			return;
-		}
-
-		let stdout = "";
-		let stderr = "";
-		const stdoutStream = childProcess.stdout;
-		const stderrStream = childProcess.stderr;
-
-		if (!stdoutStream || !stderrStream) {
-			resolve({
-				stdout: "",
-				stderr: "curl: failed to capture process output",
-				exitCode: 1,
-			});
-			return;
-		}
-
-		stdoutStream.setEncoding("utf8");
-		stderrStream.setEncoding("utf8");
-
-		stdoutStream.on("data", (chunk: string) => {
-			stdout += chunk;
-		});
-
-		stderrStream.on("data", (chunk: string) => {
-			stderr += chunk;
-		});
-
-		childProcess.on("error", (error) => {
-			const errorCode =
-				error instanceof Error && "code" in error
-					? String((error as NodeJS.ErrnoException).code ?? "")
-					: "";
-			resolve({
-				stdout: "",
-				stderr: `curl: ${error.message}`,
-				exitCode: errorCode === "ENOENT" ? 127 : 1,
-			});
-		});
-
-		childProcess.on("close", (code) => {
-			resolve({
-				stdout,
-				stderr,
-				exitCode: code ?? 1,
-			});
-		});
-	});
-}
-
 export const curlCommand: ShellModule = {
 	name: "curl",
 	params: ["[-o file] <url>"],
-	run: async ({ authUser, vfs, cwd, args }) => {
-		const outputPathValue = getFlag(args, ["-o", "--output"]);
+	run: async ({ authUser, cwd, args, shell }) => {
+		const { flagsWithValues, positionals } = parseArgs(args, {
+			flagsWithValue: ["-o", "--output"],
+		});
 		const outputPath =
-			typeof outputPathValue === "string" && outputPathValue.length > 0
-				? outputPathValue
-				: null;
-		const parserOptions = { flagsWithValue: ["-o", "--output"] };
-		const inputArgs: string[] = [];
-		for (let index = 0; ; index += 1) {
-			const arg = getArg(args, index, parserOptions);
-			if (!arg) {
-				break;
-			}
-			inputArgs.push(arg);
-		}
-		const url = inputArgs[0];
-		const isHelpLike = ifFlag(args, ["-h", "--help", "-V", "--version"]);
+			flagsWithValues.get("-o") || flagsWithValues.get("--output") || null;
+		const url = positionals[0];
 
 		if (!url) {
 			return { stderr: "curl: missing URL", exitCode: 1 };
 		}
 
-		const passthroughArgs = outputPath ? [...inputArgs, "-o", "-"] : inputArgs;
-		const result = await runHostCurl(passthroughArgs);
+		const passthroughArgs = outputPath
+			? [...positionals, "-o", "-"]
+			: positionals;
+		const result = await runHostCommand("curl", passthroughArgs);
 
 		if (result.exitCode !== 0) {
 			return {
@@ -115,7 +39,7 @@ export const curlCommand: ShellModule = {
 		if (outputPath) {
 			const target = resolvePath(cwd, outputPath);
 			assertPathAccess(authUser, target, "curl");
-			vfs.writeFile(target, result.stdout);
+			shell.vfs.writeFile(target, result.stdout);
 			return {
 				stderr: result.stderr
 					? normalizeTerminalOutput(result.stderr)
@@ -125,9 +49,7 @@ export const curlCommand: ShellModule = {
 		}
 
 		return {
-			stdout: isHelpLike
-				? normalizeTerminalOutput(result.stdout)
-				: result.stdout,
+			stdout: result.stdout,
 			stderr: result.stderr
 				? normalizeTerminalOutput(result.stderr)
 				: undefined,

package/src/VirtualShell/commands/deluser.ts

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

package/src/VirtualShell/commands/echo.ts

@@ -1,5 +1,5 @@
 import type { ShellModule } from "../../types/commands";
-import { getArg, ifFlag } from "./command-helpers";
+import { parseArgs } from "./command-helpers";
 import { getAllEnvVars } from "./set";
 
 function expandEnvVars(input: string, env: Record<string, string>): string {
@@ -12,18 +12,11 @@ export const echoCommand: ShellModule = {
 	name: "echo",
 	params: ["[options] [text...]"],
 	run: ({ args, authUser, stdin }) => {
-		const newline = !ifFlag(args, "-n");
-		const filteredArgs: string[] = [];
-		for (let index = 0; ; index += 1) {
-			const value = getArg(args, index, { flags: ["-n"] });
-			if (value === undefined) {
-				break;
-			}
-			filteredArgs.push(value);
-		}
-		const env = getAllEnvVars(authUser);
+		const { flags, positionals } = parseArgs(args, { flags: ["-n"] });
+		const newline = !flags.has("-n");
 		const rawText =
-			filteredArgs.length > 0 ? filteredArgs.join(" ") : (stdin ?? "");
+			positionals.length > 0 ? positionals.join(" ") : (stdin ?? "");
+		const env = getAllEnvVars(authUser);
 		const text = expandEnvVars(rawText, env);
 
 		return {