typescript-virtual-container 1.0.7 → 1.0.8

package/CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [1.0.6...1.0.8] - 2026-04-15
+
+Too much refactor to list.
+
 ## [1.0.5] - 2026-04-15
 
 ### Changed

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.7",
+  "version": "1.0.8",
   "license": "MIT",
   "keywords": [
     "ssh",

package/src/VirtualFileSystem/index.ts

@@ -58,6 +58,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/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"]);
+		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 {
@@ -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/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 {

package/src/VirtualShell/commands/grep.ts

@@ -1,23 +1,16 @@
 import type { ShellModule } from "../../types/commands";
-import { getArg, ifFlag } from "./command-helpers";
+import { parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
 export const grepCommand: ShellModule = {
 	name: "grep",
 	params: ["[-i] [-v] <pattern> [file...]"],
 	run: ({ authUser, vfs, cwd, args, stdin }) => {
-		const caseInsensitive = ifFlag(args, "-i");
-		const invertMatch = ifFlag(args, "-v");
-		const parserOptions = { flags: ["-i", "-v"] };
-		const pattern = getArg(args, 0, parserOptions);
-		const files: string[] = [];
-		for (let index = 1; ; index += 1) {
-			const file = getArg(args, index, parserOptions);
-			if (!file) {
-				break;
-			}
-			files.push(file);
-		}
+		const { flags, positionals } = parseArgs(args, { flags: ["-i", "-v"] });
+		const caseInsensitive = flags.has("-i");
+		const invertMatch = flags.has("-v");
+		const pattern = positionals[0];
+		const files = positionals.slice(1);
 
 		if (!pattern) {
 			return { stderr: "grep: no pattern specified", exitCode: 1 };
@@ -33,7 +26,6 @@ export const grepCommand: ShellModule = {
 
 		const results: string[] = [];
 
-		// If no files specified, read from stdin (pipe/input redirection).
 		if (files.length === 0) {
 			if (!stdin) {
 				return { stdout: "", exitCode: 1 };

package/src/VirtualShell/commands/helpers.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import * as path from "node:path";
 import type VirtualFileSystem from "../../VirtualFileSystem";
 
@@ -76,6 +77,79 @@ export async function fetchResource(
 	};
 }
 
+/**
+ * Run a host command like curl or wget and capture its output.
+ * @param binary - The binary to execute (e.g., "curl", "wget").
+ * @param args - Arguments to pass to the binary.
+ * @returns Promise resolving with stdout, stderr, and exit code.
+ */
+export function runHostCommand(
+	binary: string,
+	args: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	return new Promise((resolve) => {
+		let childProcess: ReturnType<typeof spawn>;
+
+		try {
+			childProcess = spawn(binary, args, {
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+		} catch (error) {
+			resolve({
+				stdout: "",
+				stderr: `${binary}: ${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: `${binary}: 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: `${binary}: ${error.message}`,
+				exitCode: errorCode === "ENOENT" ? 127 : 1,
+			});
+		});
+
+		childProcess.on("close", (code) => {
+			resolve({
+				stdout,
+				stderr,
+				exitCode: code ?? 1,
+			});
+		});
+	});
+}
+
 function levenshtein(a: string, b: string): number {
 	const dp: number[][] = Array.from({ length: a.length + 1 }, () =>
 		Array<number>(b.length + 1).fill(0),

package/src/VirtualShell/commands/index.ts

@@ -3,7 +3,6 @@ import type { VirtualUserManager } from "../../SSHMimic/users";
 import type {
 	CommandContext,
 	CommandMode,
-	CommandOutcome,
 	CommandResult,
 	ShellModule,
 } from "../../types/commands";
@@ -77,11 +76,29 @@ const helpCommand = createHelpCommand(() =>
 	getCommandModules().map((cmd) => cmd.name),
 );
 
+const commandRegistry = new Map<string, ShellModule>();
+let cachedCommandNames: string[] | null = null;
+
+function invalidateCache(): void {
+	cachedCommandNames = null;
+}
+
+function buildCache(): void {
+	commandRegistry.clear();
+	for (const mod of getCommandModules()) {
+		commandRegistry.set(mod.name, mod);
+		for (const alias of mod.aliases ?? []) {
+			commandRegistry.set(alias, mod);
+		}
+	}
+	cachedCommandNames = Array.from(commandRegistry.keys()).sort();
+}
+
 function getCommandModules(): ShellModule[] {
 	return [...BASE_COMMANDS, ...customCommands, helpCommand];
 }
 
-function getTakenCommandNames(modules: ShellModule[]): Set<string> {
+function _getTakenCommandNames(modules: ShellModule[]): Set<string> {
 	const taken = new Set<string>();
 	for (const mod of modules) {
 		taken.add(mod.name);
@@ -106,13 +123,14 @@ export function registerCommand(module: ShellModule): void {
 		);
 	}
 
-	const takenNames = getTakenCommandNames(getCommandModules());
-	const conflict = names.find((name) => takenNames.has(name));
-	if (conflict) {
-		throw new Error(`Command '${conflict}' already exists`);
+	for (const name of names) {
+		if (commandRegistry.has(name)) {
+			throw new Error(`Command '${name}' already exists`);
+		}
+		commandRegistry.set(name, normalized);
 	}
 
-	customCommands.push(normalized);
+	invalidateCache();
 }
 
 export function createCustomCommand(
@@ -128,17 +146,14 @@ export function createCustomCommand(
 }
 
 export function getCommandNames(): string[] {
-	return getCommandModules().flatMap((cmd) => [
-		cmd.name,
-		...(cmd.aliases ?? []),
-	]);
+	if (!cachedCommandNames) {
+		buildCache();
+	}
+	return cachedCommandNames!;
 }
 
-function resolveModule(name: string): ShellModule | undefined {
-	const lowered = name.toLowerCase();
-	return getCommandModules().find(
-		(cmd) => cmd.name === lowered || cmd.aliases?.includes(lowered),
-	);
+export function resolveModule(name: string): ShellModule | undefined {
+	return commandRegistry.get(name.toLowerCase());
 }
 
 function splitArgsRespectingQuotes(input: string): string[] {
@@ -192,7 +207,7 @@ function parseInput(rawInput: string): { commandName: string; args: string[] } {
 }
 
 // Internal async function for pipeline execution
-async function runCommandInternal(
+async function _runCommandInternal(
 	rawInput: string,
 	authUser: string,
 	hostname: string,
@@ -271,7 +286,7 @@ async function runCommandInternal(
 	}
 }
 
-export function runCommand(
+export async function runCommand(
 	rawInput: string,
 	authUser: string,
 	hostname: string,
@@ -281,29 +296,42 @@ export function runCommand(
 	shellProps: ShellProperties,
 	vfs: VirtualFileSystem,
 	stdin?: string,
-): CommandOutcome {
+): Promise<CommandResult> {
 	const trimmed = rawInput.trim();
 
 	if (trimmed.length === 0) {
 		return { exitCode: 0 };
 	}
 
-	// Check if input contains pipes or redirections - use async version
 	if (trimmed.includes("|") || trimmed.includes(">") || trimmed.includes("<")) {
-		return runCommandInternal(
-			trimmed,
-			authUser,
-			hostname,
-			users,
-			mode,
-			cwd,
-			shellProps,
-			vfs,
-			stdin,
-		);
+		const { parseShellPipeline } = await import("../shellParser");
+		const { executePipeline } = await import("../../SSHMimic/executor");
+
+		const pipeline = parseShellPipeline(trimmed);
+		if (!pipeline.isValid) {
+			return {
+				stderr: pipeline.error || "Syntax error",
+				exitCode: 1,
+			};
+		}
+
+		try {
+			return await executePipeline(
+				pipeline,
+				authUser,
+				hostname,
+				users,
+				mode,
+				cwd,
+				vfs,
+			);
+		} catch (error: unknown) {
+			const message =
+				error instanceof Error ? error.message : "Pipeline execution failed";
+			return { stderr: message, exitCode: 1 };
+		}
 	}
 
-	// Regular synchronous command execution
 	const { commandName, args } = parseInput(trimmed);
 	const mod = resolveModule(commandName);
 
@@ -315,7 +343,7 @@ export function runCommand(
 	}
 
 	try {
-		return mod.run({
+		return await mod.run({
 			authUser,
 			hostname,
 			users,

package/src/VirtualShell/commands/sudo.ts

@@ -1,6 +1,6 @@
 import { defaultShellProperties } from "..";
 import type { ShellModule } from "../../types/commands";
-import { getArg, getFlag, ifFlag } from "./command-helpers";
+import { parseArgs } from "./command-helpers";
 import { runCommand } from "./index";
 
 function parseSudoArgs(args: string[]): {
@@ -8,26 +8,16 @@ function parseSudoArgs(args: string[]): {
 	loginShell: boolean;
 	commandLine: string | null;
 } {
-	const loginShell = ifFlag(args, "-i");
-	const targetUserValue = getFlag(args, ["-u", "--user"]);
-	const targetUser =
-		typeof targetUserValue === "string" && targetUserValue.length > 0
-			? targetUserValue
-			: "root";
+	const { flags, flagsWithValues, positionals } = parseArgs(args, {
+		flags: ["-i", "-S"],
+		flagsWithValue: ["-u", "--user"],
+	});
 
-	const commandParts: string[] = [];
-	for (let index = 0; ; index += 1) {
-		const part = getArg(args, index, {
-			flags: ["-i", "-S"],
-			flagsWithValue: ["-u", "--user"],
-		});
-		if (!part) {
-			break;
-		}
-		commandParts.push(part);
-	}
+	const loginShell = flags.has("-i");
+	const targetUser =
+		flagsWithValues.get("-u") || flagsWithValues.get("--user") || "root";
+	const commandLine = positionals.length > 0 ? positionals.join(" ") : null;
 
-	const commandLine = commandParts.length > 0 ? commandParts.join(" ") : null;
 	return { targetUser, loginShell, commandLine };
 }
 export const sudoCommand: ShellModule = {

package/src/VirtualShell/commands/wget.ts

@@ -3,11 +3,12 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ShellModule } from "../../types/commands";
-import { getArg, getFlag, ifFlag } from "./command-helpers";
+import { ifFlag, parseArgs } from "./command-helpers";
 import {
 	assertPathAccess,
 	normalizeTerminalOutput,
 	resolvePath,
+	runHostCommand,
 	stripUrlFilename,
 } from "./helpers";
 
@@ -83,36 +84,25 @@ export const wgetCommand: ShellModule = {
 	name: "wget",
 	params: ["[url]"],
 	run: async ({ authUser, vfs, cwd, args }) => {
-		const outputPathValue = getFlag(args, [
-			"-o",
-			"-O",
-			"--output",
-			"--output-document",
-		]);
-		const outputPath =
-			typeof outputPathValue === "string" && outputPathValue.length > 0
-				? outputPathValue
-				: null;
-		const parserOptions = {
+		const { flagsWithValues, positionals } = parseArgs(args, {
 			flagsWithValue: ["-o", "-O", "--output", "--output-document"],
-		};
-		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"]);
+		});
+		const outputPath =
+			flagsWithValues.get("-o") ||
+			flagsWithValues.get("-O") ||
+			flagsWithValues.get("--output") ||
+			flagsWithValues.get("--output-document") ||
+			null;
+		const url = positionals[0];
 
 		if (!url) {
 			return { stderr: "wget: missing URL", exitCode: 1 };
 		}
 
+		const isHelpLike = ifFlag(args, ["-h", "--help", "-V", "--version"]);
+
 		if (isHelpLike) {
-			const result = await runHostWget(inputArgs);
+			const result = await runHostWget(args);
 			return {
 				stdout: normalizeTerminalOutput(result.stdout),
 				stderr: result.stderr
@@ -126,8 +116,8 @@ export const wgetCommand: ShellModule = {
 		const tempFile = join(tempDir, "download");
 
 		try {
-			const hostArgs = [...inputArgs, "-O", tempFile];
-			const result = await runHostWget(hostArgs);
+			const hostArgs = [...positionals, "-O", tempFile];
+			const result = await runHostCommand("wget", hostArgs);
 
 			if (result.exitCode !== 0) {
 				return {
@@ -139,7 +129,7 @@ export const wgetCommand: ShellModule = {
 			}
 
 			const content = await readFile(tempFile, "utf8");
-			const target = resolvePath(cwd, outputPath ?? stripUrlFilename(url));
+			const target = resolvePath(cwd, outputPath || stripUrlFilename(url));
 			assertPathAccess(authUser, target, "wget");
 			vfs.writeFile(target, content);
 

package/src/VirtualShell/shell.ts

@@ -66,6 +66,9 @@ export function startShell(
 		return buildPrompt(authUser, hostname, cwdLabel);
 	};
 	const commandNames = Array.from(new Set(getCommandNames())).sort();
+	console.log(
+		`[${sessionId}] Shell started for user '${authUser}' at ${remoteAddress}`,
+	);
 
 	async function collectChildPids(parentPid: number): Promise<number[]> {
 		try {

package/tests/parser-executor.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { executePipeline } from "../src/SSHMimic/executor";
+import { VirtualUserManager } from "../src/SSHMimic/users";
+import VirtualFileSystem from "../src/VirtualFileSystem";
+import { parseShellPipeline } from "../src/VirtualShell/shellParser";
+
+describe("Pipeline parser and executor", () => {
+  test("parses simple pipeline", () => {
+    const pipeline = parseShellPipeline("echo hello | grep h");
+    expect(pipeline.isValid).toBe(true);
+    expect(pipeline.commands).toHaveLength(2);
+    expect(pipeline.commands[0]?.name).toBe("echo");
+    expect(pipeline.commands[1]?.name).toBe("grep");
+  });
+
+  test("handles invalid syntax", () => {
+    const pipeline = parseShellPipeline("echo hello |");
+    expect(pipeline.isValid).toBe(false);
+    expect(pipeline.error).toBeDefined();
+  });
+
+  test("executes simple pipeline", async () => {
+    const vfs = new VirtualFileSystem("/tmp");
+    const users = new VirtualUserManager(vfs, "root-pass");
+    const pipeline = parseShellPipeline("echo hello | grep h");
+
+    const result = await executePipeline(
+      pipeline,
+      "root",
+      "localhost",
+      users,
+      "shell",
+      "/",
+      vfs,
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("hello");
+  });
+});