typescript-virtual-container 1.0.8 → 1.1.1

package/src/{SSHMimic/client.ts → SSHClient/index.ts}

@@ -1,19 +1,17 @@
+import { runCommand } from "../commands";
 import type { CommandResult } from "../types/commands";
-import { runCommand } from "../VirtualShell/commands";
-import type { SshMimic } from "./index";
+import type { VirtualShell } from "../VirtualShell";
 
 /**
- * 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,13 +148,13 @@ 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");
 		}
 
 		try {
-			vfs.writeFile(path, content);
+			this.shell.writeFileAsUser(this.username, path, content);
 			return { stdout: `File '${path}' written`, exitCode: 0 };
 		} catch (error) {
 			return {
@@ -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 { runCommand } from "../commands";
 import type { ExecStream } from "../types/streams";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import { defaultShellProperties } from "../VirtualShell";
-import { runCommand } from "../VirtualShell/commands";
-import type { VirtualUserManager } from "./users";
+import type { VirtualShell } from "../VirtualShell";
 
 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();
 	});
 }

package/src/SSHMimic/executor.ts

@@ -1,10 +1,8 @@
+import { runCommand as runSingleCommand } from "../commands";
+import { resolvePath } from "../commands/helpers";
 import type { CommandMode, CommandResult } from "../types/commands";
 import type { Pipeline, PipelineCommand } from "../types/pipeline";
-import type VirtualFileSystem from "../VirtualFileSystem";
-import { defaultShellProperties } from "../VirtualShell";
-import { runCommand as runSingleCommand } from "../VirtualShell/commands";
-import { resolvePath } from "../VirtualShell/commands/helpers";
-import type { VirtualUserManager } from "./users";
+import type { VirtualShell } from "../VirtualShell";
 
 /**
  * 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.writeFileAsUser(authUser, outputPath, existing + output);
 				} catch {
-					vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, outputPath, output);
 				}
 			} else {
-				vfs.writeFile(outputPath, output);
+				shell.writeFileAsUser(authUser, 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.writeFileAsUser(authUser, outputPath, existing + output);
 					} catch {
-						vfs.writeFile(outputPath, output);
+						shell.writeFileAsUser(authUser, outputPath, output);
 					}
 				} else {
-					vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, 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

@@ -24,6 +24,18 @@ class VirtualFileSystem {
 	private readonly archivePath: string;
 	private dirty = false;
 
+	private computeNodeUsageBytes(node: InternalNode): number {
+		if (node.type === "file") {
+			return node.content.length;
+		}
+
+		let total = 0;
+		for (const child of node.children.values()) {
+			total += this.computeNodeUsageBytes(child);
+		}
+		return total;
+	}
+
 	/**
 	 * Creates a virtual filesystem instance.
 	 *
@@ -49,7 +61,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);
@@ -288,6 +299,20 @@ class VirtualFileSystem {
 		return renderTree(node, rootLabel);
 	}
 
+	/**
+	 * Computes total stored file bytes under a path.
+	 *
+	 * File usage is based on in-memory stored bytes, including compressed
+	 * payload size when files are marked as compressed.
+	 *
+	 * @param targetPath File or directory path to measure, defaults to root.
+	 * @returns Total byte usage for file content under target path.
+	 */
+	public getUsageBytes(targetPath: string = "/"): number {
+		const node = getNode(this.root, targetPath);
+		return this.computeNodeUsageBytes(node);
+	}
+
 	/**
 	 * Compresses file content with gzip and flags node as compressed.
 	 *