typescript-virtual-container 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [1.0.5] - 2026-04-15
+
+### Changed
+
+- Refactored commands to use shared argument/flag parsing helpers.
+- Improved maintainability and consistency of argument parsing across commands.
+
+### Fixed
+
+- Verified all refactored commands pass existing test cases without regressions.
+
 ## [1.0.4] - 2026-04-15
 
 ### Added

package/README.md

@@ -417,6 +417,56 @@ console.log(client.getUsername());  // Username from constructor
 
 ---
 
+### VirtualShell
+
+Encapsulates shell execution primitives used by the SSH runtime for command dispatch and interactive sessions.
+
+#### Constructor
+
+```typescript
+new VirtualShell(
+	vfs: VirtualFileSystem,
+	users: VirtualUserManager,
+	hostname: 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.
+
+**Example:**
+
+```typescript
+const shell = new VirtualShell(vfs, users, "typescript-vm");
+```
+
+#### Methods
+
+##### `executeCommand(rawInput: string, authUser: string, cwd: string): void`
+
+Runs one command input in shell mode for a given user and working directory.
+
+```typescript
+shell.executeCommand("ls -la", "root", "/home/root");
+```
+
+##### `startInteractiveSession(stream: ShellStream, authUser: string, sessionId: string | null, remoteAddress: string, terminalSize: { cols: number; rows: number }): void`
+
+Starts an interactive shell session over a shell stream.
+
+```typescript
+shell.startInteractiveSession(
+	stream,
+	"root",
+	sessionId,
+	"127.0.0.1",
+	{ cols: 120, rows: 30 },
+);
+```
+
+---
+
 ### VirtualFileSystem
 
 In-memory filesystem with optional gzip compression and tar.gz persistence.

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

package/src/SSHMimic/client.ts

@@ -1,5 +1,5 @@
 import type { CommandResult } from "../types/commands";
-import { runCommand } from "./commands";
+import { runCommand } from "../VirtualShell/commands";
 import type { SshMimic } from "./index";
 
 /**

package/src/SSHMimic/exec.ts

@@ -1,6 +1,6 @@
 import type { ExecStream } from "../types/streams";
 import type VirtualFileSystem from "../VirtualFileSystem";
-import { runCommand } from "./commands";
+import { runCommand } from "../VirtualShell/commands";
 import type { VirtualUserManager } from "./users";
 
 function toTtyLines(text: string): string {

package/src/SSHMimic/executor.ts

@@ -1,8 +1,8 @@
 import type { CommandMode, CommandResult } from "../types/commands";
 import type { Pipeline, PipelineCommand } from "../types/pipeline";
 import type VirtualFileSystem from "../VirtualFileSystem";
-import { runCommand as runSingleCommand } from "./commands";
-import { resolvePath } from "./commands/helpers";
+import { runCommand as runSingleCommand } from "../VirtualShell/commands";
+import { resolvePath } from "../VirtualShell/commands/helpers";
 import type { VirtualUserManager } from "./users";
 
 /**

package/src/SSHMimic/index.ts

@@ -1,9 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { Server as SshServer } from "ssh2";
 import VirtualFileSystem from "../VirtualFileSystem";
-import { runExec } from "./exec";
+import { VirtualShell } from "../VirtualShell";
 import { loadOrCreateHostKey } from "./hostKey";
-import { startShell } from "./shell";
 import { VirtualUserManager } from "./users";
 
 function resolveRootPassword(): string {
@@ -35,12 +34,13 @@ function resolveAutoSudoForNewUsers(): boolean {
  * {@link SshMimic.stop} when your process exits.
  */
 class SshMimic {
-	private port: number;
-	private hostname: string;
-	private server: SshServer | null;
-	private vfs: VirtualFileSystem | null = null;
-	private users: VirtualUserManager | null = null;
-	private basePath: string = ".";
+	port: number;
+	hostname: string;
+	server: SshServer | null;
+	vfs: VirtualFileSystem | null = null;
+	users: VirtualUserManager | null = null;
+	shell: VirtualShell | null = null;
+	basePath: string = ".";
 
 	/**
 	 * Creates a new SSH mimic server instance.
@@ -80,6 +80,8 @@ class SshMimic {
 		);
 		await this.users.initialize();
 
+		this.shell = new VirtualShell(this.vfs, this.users, this.hostname);
+
 		this.server = new SshServer(
 			{
 				hostKeys: [privateKey],
@@ -148,12 +150,9 @@ class SshMimic {
 
 						session.on("shell", (acceptShell) => {
 							const stream = acceptShell();
-							startShell(
+							this.shell?.startInteractiveSession(
 								stream,
 								authUser,
-								this.vfs!,
-								this.hostname,
-								this.users!,
 								sessionId,
 								remoteAddress,
 								terminalSize,
@@ -161,14 +160,11 @@ class SshMimic {
 						});
 
 						session.on("exec", (acceptExec, _rejectExec, info) => {
-							const stream = acceptExec();
-							runExec(
-								stream,
+							const _stream = acceptExec();
+							this.shell?.executeCommand(
 								info.command.trim(),
 								authUser,
-								this.hostname,
-								this.users!,
-								this.vfs!,
+								`/home/${authUser}`,
 							);
 						});
 					});

package/src/{VirtualFileSystem.ts → VirtualFileSystem/index.ts}

@@ -5,21 +5,12 @@ import type {
 	RemoveOptions,
 	VfsNodeStats,
 	WriteFileOptions,
-} from "./types/vfs";
-import {
-	archiveExists,
-	createTarBuffer,
-	readSnapshotFromTar,
-} from "./vfs/archive";
-import type { InternalDirectoryNode, InternalNode } from "./vfs/internalTypes";
-import {
-	getNode,
-	getParentDirectory,
-	normalizePath,
-	splitPath,
-} from "./vfs/path";
-import { applySnapshot, createSnapshot } from "./vfs/snapshot";
-import { renderTree } from "./vfs/tree";
+} from "../types/vfs";
+import { archiveExists, createTarBuffer, readSnapshotFromTar } from "./archive";
+import type { InternalDirectoryNode, InternalNode } from "./internalTypes";
+import { getNode, getParentDirectory, normalizePath, splitPath } from "./path";
+import { applySnapshot, createSnapshot } from "./snapshot";
+import { renderTree } from "./tree";
 
 /**
  * In-memory virtual filesystem with tar.gz mirror persistence.

package/src/{SSHMimic → VirtualShell}/commands/cat.ts

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

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

@@ -0,0 +1,135 @@
+type ArgParseOptions = {
+	flags?: string[];
+	flagsWithValue?: string[];
+};
+
+function toFlagList(flags: string | string[]): string[] {
+	return Array.isArray(flags) ? flags : [flags];
+}
+
+function matchFlagToken(
+	token: string,
+	flag: string,
+): { matched: boolean; inlineValue: string | null } {
+	if (token === flag) {
+		return { matched: true, inlineValue: null };
+	}
+
+	const prefix = `${flag}=`;
+	if (token.startsWith(prefix)) {
+		return { matched: true, inlineValue: token.slice(prefix.length) };
+	}
+
+	return { matched: false, inlineValue: null };
+}
+
+function collectPositionals(
+	args: string[],
+	options: ArgParseOptions = {},
+): string[] {
+	const boolFlags = new Set(options.flags ?? []);
+	const valueFlags = new Set(options.flagsWithValue ?? []);
+	const positionals: string[] = [];
+	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;
+		}
+
+		let consumed = false;
+
+		for (const flag of boolFlags) {
+			const { matched } = matchFlagToken(arg, flag);
+			if (matched) {
+				consumed = true;
+				break;
+			}
+		}
+
+		if (consumed) {
+			continue;
+		}
+
+		for (const flag of valueFlags) {
+			const match = matchFlagToken(arg, flag);
+			if (!match.matched) {
+				continue;
+			}
+
+			consumed = true;
+			if (match.inlineValue === null && index + 1 < args.length) {
+				index += 1;
+			}
+			break;
+		}
+
+		if (!consumed) {
+			positionals.push(arg);
+		}
+	}
+
+	return positionals;
+}
+
+export function ifFlag(args: string[], flags: string | string[]): boolean {
+	const allFlags = toFlagList(flags);
+
+	for (const arg of args) {
+		for (const flag of allFlags) {
+			if (matchFlagToken(arg, flag).matched) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+export function getFlag(
+	args: string[],
+	flags: string | string[],
+): string | true | undefined {
+	const allFlags = toFlagList(flags);
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index]!;
+
+		for (const flag of allFlags) {
+			const match = matchFlagToken(arg, flag);
+			if (!match.matched) {
+				continue;
+			}
+
+			if (match.inlineValue !== null) {
+				return match.inlineValue;
+			}
+
+			const next = args[index + 1];
+			if (next !== undefined && next !== "--") {
+				return next;
+			}
+
+			return true;
+		}
+	}
+
+	return undefined;
+}
+
+export function getArg(
+	args: string[],
+	index: number,
+	options: ArgParseOptions = {},
+): string | undefined {
+	const positionals = collectPositionals(args, options);
+	return positionals[index];
+}

package/src/{SSHMimic → VirtualShell}/commands/curl.ts

@@ -1,43 +1,12 @@
 import { spawn } from "node:child_process";
 import type { ShellModule } from "../../types/commands";
+import { getArg, getFlag, ifFlag } from "./command-helpers";
 import {
 	assertPathAccess,
 	normalizeTerminalOutput,
 	resolvePath,
 } from "./helpers";
 
-function parseCurlOutputPath(args: string[]): {
-	outputPath: string | null;
-	inputArgs: string[];
-} {
-	const filtered: string[] = [];
-	let outputPath: string | null = null;
-
-	for (let index = 0; index < args.length; index += 1) {
-		const arg = args[index]!;
-
-		if (arg === "-o" || arg === "--output") {
-			outputPath = args[index + 1] ?? null;
-			index += 1;
-			continue;
-		}
-
-		if (arg.startsWith("-o=")) {
-			outputPath = arg.slice(3);
-			continue;
-		}
-
-		if (arg.startsWith("--output=")) {
-			outputPath = arg.slice("--output=".length);
-			continue;
-		}
-
-		filtered.push(arg);
-	}
-
-	return { outputPath, inputArgs: filtered };
-}
-
 function runHostCurl(args: string[]): Promise<{
 	stdout: string;
 	stderr: string;
@@ -110,12 +79,22 @@ export const curlCommand: ShellModule = {
 	name: "curl",
 	params: ["[-o file] <url>"],
 	run: async ({ authUser, vfs, cwd, args }) => {
-		const { outputPath, inputArgs } = parseCurlOutputPath(args);
+		const outputPathValue = getFlag(args, ["-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 = inputArgs.some(
-			(arg) =>
-				arg === "-h" || arg === "--help" || arg === "-V" || arg === "--version",
-		);
+		const isHelpLike = ifFlag(args, ["-h", "--help", "-V", "--version"]);
 
 		if (!url) {
 			return { stderr: "curl: missing URL", exitCode: 1 };

package/src/{SSHMimic → VirtualShell}/commands/echo.ts

@@ -1,4 +1,5 @@
 import type { ShellModule } from "../../types/commands";
+import { getArg, ifFlag } from "./command-helpers";
 import { getAllEnvVars } from "./set";
 
 function expandEnvVars(input: string, env: Record<string, string>): string {
@@ -11,8 +12,15 @@ export const echoCommand: ShellModule = {
 	name: "echo",
 	params: ["[options] [text...]"],
 	run: ({ args, authUser, stdin }) => {
-		const newline = !args.includes("-n");
-		const filteredArgs = args.filter((arg) => arg !== "-n");
+		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 rawText =
 			filteredArgs.length > 0 ? filteredArgs.join(" ") : (stdin ?? "");

package/src/{SSHMimic → VirtualShell}/commands/export.ts

@@ -1,4 +1,5 @@
 import type { ShellModule } from "../../types/commands";
+import { getArg } from "./command-helpers";
 import { getEnvVar, setEnvVar } from "./set";
 
 export const exportCommand: ShellModule = {
@@ -15,7 +16,12 @@ export const exportCommand: ShellModule = {
 		}
 
 		// Parse VAR=value format
-		for (const arg of args) {
+		for (let index = 0; ; index += 1) {
+			const arg = getArg(args, index);
+			if (!arg) {
+				break;
+			}
+
 			if (arg.includes("=")) {
 				const [varName, varValue] = arg.split("=", 2);
 				if (varName && varValue !== undefined) {

package/src/{SSHMimic → VirtualShell}/commands/grep.ts

@@ -1,25 +1,32 @@
 import type { ShellModule } from "../../types/commands";
+import { getArg, ifFlag } 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 = args.includes("-i");
-		const invertMatch = args.includes("-v");
-		const filteredArgs = args.filter((arg) => arg !== "-i" && arg !== "-v");
+		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);
+		}
 
-		if (filteredArgs.length === 0) {
+		if (!pattern) {
 			return { stderr: "grep: no pattern specified", exitCode: 1 };
 		}
 
-		const pattern = filteredArgs[0];
-		const files = filteredArgs.slice(1);
-
 		let regex: RegExp;
 		try {
 			const flags = caseInsensitive ? "gmi" : "gm";
-			regex = new RegExp(pattern as string, flags);
+			regex = new RegExp(pattern, flags);
 		} catch {
 			return { stderr: `grep: invalid regex: ${pattern}`, exitCode: 1 };
 		}

package/src/{SSHMimic → VirtualShell}/commands/helpers.ts

@@ -58,43 +58,6 @@ export function assertPathAccess(
 	}
 }
 
-export function parseOutputPath(args: string[]): {
-	outputPath: string | null;
-	inputArgs: string[];
-} {
-	const filtered: string[] = [];
-	let outputPath: string | null = null;
-
-	for (let index = 0; index < args.length; index += 1) {
-		const arg = args[index]!;
-
-		if (
-			arg === "-o" ||
-			arg === "-O" ||
-			arg === "--output" ||
-			arg === "--output-document"
-		) {
-			outputPath = args[index + 1] ?? null;
-			index += 1;
-			continue;
-		}
-
-		if (arg.startsWith("-o=")) {
-			outputPath = arg.slice(3);
-			continue;
-		}
-
-		if (arg.startsWith("-O=")) {
-			outputPath = arg.slice(3);
-			continue;
-		}
-
-		filtered.push(arg);
-	}
-
-	return { outputPath, inputArgs: filtered };
-}
-
 export function stripUrlFilename(url: string): string {
 	const cleaned = url.split("?")[0]?.split("#")[0] ?? url;
 	const lastPart = cleaned.split("/").filter(Boolean).pop();

package/src/{SSHMimic → VirtualShell}/commands/index.ts

@@ -1,11 +1,12 @@
+import type { VirtualUserManager } from "../../SSHMimic/users";
 import type {
+	CommandContext,
 	CommandMode,
 	CommandOutcome,
 	CommandResult,
 	ShellModule,
 } from "../../types/commands";
 import type VirtualFileSystem from "../../VirtualFileSystem";
-import type { VirtualUserManager } from "../users";
 import { adduserCommand } from "./adduser";
 import { catCommand } from "./cat";
 import { cdCommand } from "./cd";
@@ -67,18 +68,72 @@ const BASE_COMMANDS: ShellModule[] = [
 	exitCommand,
 ];
 
-const COMMANDS: ShellModule[] = [
-	...BASE_COMMANDS,
-	createHelpCommand(() => COMMANDS.map((cmd) => cmd.name)),
-];
+const customCommands: ShellModule[] = [];
+
+const helpCommand = createHelpCommand(() =>
+	getCommandModules().map((cmd) => cmd.name),
+);
+
+function getCommandModules(): ShellModule[] {
+	return [...BASE_COMMANDS, ...customCommands, helpCommand];
+}
+
+function getTakenCommandNames(modules: ShellModule[]): Set<string> {
+	const taken = new Set<string>();
+	for (const mod of modules) {
+		taken.add(mod.name);
+		for (const alias of mod.aliases ?? []) {
+			taken.add(alias);
+		}
+	}
+	return taken;
+}
+
+export function registerCommand(module: ShellModule): void {
+	const normalized: ShellModule = {
+		...module,
+		name: module.name.trim().toLowerCase(),
+		aliases: module.aliases?.map((alias) => alias.trim().toLowerCase()),
+	};
+
+	const names = [normalized.name, ...(normalized.aliases ?? [])];
+	if (names.some((name) => name.length === 0 || /\s/.test(name))) {
+		throw new Error(
+			"Command names and aliases must be non-empty and contain no spaces",
+		);
+	}
+
+	const takenNames = getTakenCommandNames(getCommandModules());
+	const conflict = names.find((name) => takenNames.has(name));
+	if (conflict) {
+		throw new Error(`Command '${conflict}' already exists`);
+	}
+
+	customCommands.push(normalized);
+}
+
+export function createCustomCommand(
+	name: string,
+	params: string[],
+	run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>,
+): ShellModule {
+	return {
+		name,
+		params,
+		run,
+	};
+}
 
 export function getCommandNames(): string[] {
-	return COMMANDS.flatMap((cmd) => [cmd.name, ...(cmd.aliases ?? [])]);
+	return getCommandModules().flatMap((cmd) => [
+		cmd.name,
+		...(cmd.aliases ?? []),
+	]);
 }
 
 function resolveModule(name: string): ShellModule | undefined {
 	const lowered = name.toLowerCase();
-	return COMMANDS.find(
+	return getCommandModules().find(
 		(cmd) => cmd.name === lowered || cmd.aliases?.includes(lowered),
 	);
 }
@@ -152,7 +207,7 @@ async function runCommandInternal(
 	) {
 		// Use pipeline executor
 		const { parseShellPipeline } = await import("../shellParser");
-		const { executePipeline } = await import("../executor");
+		const { executePipeline } = await import("../../SSHMimic/executor");
 
 		const pipeline = parseShellPipeline(rawInput);
 		if (!pipeline.isValid) {

package/src/{SSHMimic → VirtualShell}/commands/ls.ts

@@ -1,4 +1,5 @@
 import type { ShellModule } from "../../types/commands";
+import { getArg, ifFlag } from "./command-helpers";
 import { assertPathAccess, joinListWithType, resolvePath } from "./helpers";
 
 function formatPermissions(mode: number, isDirectory: boolean): string {
@@ -29,8 +30,8 @@ export const lsCommand: ShellModule = {
 	name: "ls",
 	params: ["[path]"],
 	run: ({ authUser, vfs, cwd, args }) => {
-		const longFormat = args.includes("-l") || args.includes("--long");
-		const targetArg = args.find((arg) => !arg.startsWith("-"));
+		const longFormat = ifFlag(args, ["-l", "--long"]);
+		const targetArg = getArg(args, 0, { flags: ["-l", "--long"] });
 		const target = resolvePath(cwd, targetArg ?? cwd);
 		assertPathAccess(authUser, target, "ls");
 		const items = vfs.list(target).filter((name) => !name.startsWith("."));