typescript-virtual-container 1.0.3 → 1.0.5

package/.github/workflows/test-battery.yml

@@ -70,10 +70,32 @@ jobs:
       - name: Run lint
         run: bun lint
 
+  tests:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Restore dependencies
+        uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
+
+      - name: Run tests
+        run: bun test
+
   test-battery:
     needs:
       - typecheck
       - lint
+      - tests
     runs-on: ubuntu-latest
     steps:
       - name: Test battery passed

package/CHANGELOG.md

@@ -6,6 +6,48 @@ 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
+
+- Shell pipeline parser and executor with support for:
+  - Pipes (`|`)
+  - Input redirection (`<`)
+  - Output redirection (`>`)
+  - Append redirection (`>>`)
+- New built-in commands:
+  - `echo`
+  - `grep`
+  - `set`
+  - `env`
+  - `export`
+  - `unset`
+  - `sh` (with `bash` alias)
+- Command stdin support in runtime context so commands can consume piped input.
+
+### Changed
+
+- Argument parsing now respects quoted strings, including for commands like `sh -c "echo hi"`.
+- `echo` now expands environment variables (`$VAR`) and can read from stdin when no explicit text argument is provided.
+- `grep` now supports stdin input (e.g. `ls | grep ".txt"`) in addition to file operands.
+
+### Fixed
+
+- Relative file paths in redirections are now resolved from current working directory during pipeline execution.
+  - Example fixed behavior: `echo hi > cat.txt` writes to `./cat.txt` in current virtual directory.
+- Pipeline chaining now correctly passes command stdout as stdin to next command.
+
 ## [1.0.2] - 2026-04-14
 
 ### Added

package/README.md

@@ -39,7 +39,7 @@
 - **Virtual Filesystem**: In-memory filesystem with optional compression, persistence to disk via tar.gz snapshots, and programmatic access.
 - **User Management**: Create, authenticate, and manage virtual users with strict password hashing (scrypt) and sudo-like privilege elevation.
 - **Programmatic Shell API**: Execute shell commands and query filesystem state directly from TypeScript without SSH overhead.
-- **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and more.
+- **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and a growing set of additional commands. Not everything is implemented yet, and shell compatibility is still being expanded.
 - **Full TypeScript Support**: Complete JSDoc coverage, exported types, and first-class async/await for all operations.
 
 ## Why This Package
@@ -140,7 +140,7 @@ ssh.stop();
 
 ## Architecture Overview
 
-### Core Components
+<!-- ### Core Components
 
 ```
 ┌─────────────────────────────────────────────┐
@@ -158,7 +158,7 @@ ssh.stop();
 │              Backed by disk
 │              .vfs/mirror.tar.gz
 └──────────────────────────────────┘
-```
+``` -->
 
 ### Execution Modes
 
@@ -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.
@@ -1006,7 +1056,7 @@ ssh.stop();
 
 ## Built-in Commands
 
-The following commands are available in both SSH shell mode and via `SshClient.exec()`:
+The following commands are available in both SSH shell mode and via `SshClient.exec()`. This list is intentionally incomplete: some commands, flags, and edge cases are still missing or only partially compatible with real shells, and that will continue to be worked on.
 
 | Command | Purpose | Notes |
 |---------|---------|-------|
@@ -1125,7 +1175,7 @@ No. It emulates SSH sessions, users, and filesystem behavior in memory. It is id
 
 ### Can I use this in production?
 
-You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments), but it is not a security boundary like a real container/VM.
+You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments), but it is not a security boundary like a real container/VM. And at the moment, all commands are not implemented with full fidelity, so it may not be suitable for all production use cases.
 
 ### Does data persist between restarts?
 
@@ -1262,26 +1312,4 @@ MIT License. See LICENSE file for details.
 - [ ] Improved shell compatibility for complex piping and redirection
 - [ ] Snapshot diff tooling for test assertions
 - [ ] Structured event hooks (session open/close, file write, sudo challenge)
-
----
-
-## Changelog
-
-### v1.0.0 (2026-04-14)
-
-**Initial Release**
-
-- ✨ SSH server with password auth
-- ✨ Virtual filesystem with persistence
-- ✨ User management & sudoers
-- ✨ Programmatic `SshClient` API
-- ✨ 20+ built-in shell commands
-- ✨ Full TypeScript support & JSDoc coverage
-- ✨ tar.gz snapshot persistence
-- ✨ Session & TTY management
-- ✨ Interactive `nano` editor
-- ✨ Sudo/su privilege escalation
-
----
-
-**Made with ❤️ for testing, automation, and interactive TypeScript development.**
+- [ ] WebSocket-based remote shell client (experimental)

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.3",
+  "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

@@ -0,0 +1,201 @@
+import type { CommandMode, CommandResult } from "../types/commands";
+import type { Pipeline, PipelineCommand } from "../types/pipeline";
+import type VirtualFileSystem from "../VirtualFileSystem";
+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.
+ * Manages stdout/stderr flow between commands and file I/O.
+ */
+export async function executePipeline(
+	pipeline: Pipeline,
+	authUser: string,
+	hostname: string,
+	users: VirtualUserManager,
+	mode: CommandMode,
+	cwd: string,
+	vfs: VirtualFileSystem,
+): Promise<CommandResult> {
+	if (pipeline.commands.length === 0) {
+		return { exitCode: 0 };
+	}
+
+	if (pipeline.commands.length === 1) {
+		// Single command with possible redirections
+		return executeSingleCommandWithRedirections(
+			pipeline.commands[0] as PipelineCommand,
+			authUser,
+			hostname,
+			users,
+			mode,
+			cwd,
+			vfs,
+		);
+	}
+
+	// Multiple commands in a pipeline
+	return executePipelineChain(
+		pipeline.commands as PipelineCommand[],
+		authUser,
+		hostname,
+		users,
+		mode,
+		cwd,
+		vfs,
+	);
+}
+
+/**
+ * Execute a single command with input/output redirections
+ */
+async function executeSingleCommandWithRedirections(
+	cmd: PipelineCommand,
+	authUser: string,
+	hostname: string,
+	users: VirtualUserManager,
+	mode: CommandMode,
+	cwd: string,
+	vfs: VirtualFileSystem,
+): 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);
+		} catch {
+			return {
+				stderr: `cat: ${cmd.inputFile}: No such file or directory`,
+				exitCode: 1,
+			};
+		}
+	}
+
+	// Build raw input for the command
+	const rawInput = [cmd.name, ...cmd.args].join(" ");
+
+	// Run the command with potential input
+	const result = await runSingleCommand(
+		rawInput,
+		authUser,
+		hostname,
+		users,
+		mode,
+		cwd,
+		vfs,
+		stdin,
+	);
+
+	// Handle output redirection
+	if (cmd.outputFile) {
+		const outputPath = resolvePath(cwd, cmd.outputFile);
+		const output = result.stdout || "";
+		try {
+			if (cmd.appendOutput) {
+				try {
+					const existing = vfs.readFile(outputPath);
+					vfs.writeFile(outputPath, existing + output);
+				} catch {
+					vfs.writeFile(outputPath, output);
+				}
+			} else {
+				vfs.writeFile(outputPath, output);
+			}
+			return { ...result, stdout: "" };
+		} catch {
+			return {
+				...result,
+				stderr: `Failed to write to ${cmd.outputFile}`,
+				exitCode: 1,
+			};
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Execute a chain of commands connected by pipes
+ */
+async function executePipelineChain(
+	commands: PipelineCommand[],
+	authUser: string,
+	hostname: string,
+	users: VirtualUserManager,
+	mode: CommandMode,
+	cwd: string,
+	vfs: VirtualFileSystem,
+): Promise<CommandResult> {
+	let currentOutput = "";
+	let exitCode = 0;
+
+	for (let i = 0; i < commands.length; i++) {
+		const cmd = commands[i] as PipelineCommand;
+
+		// Handle input file for first command
+		if (i === 0 && cmd.inputFile) {
+			const inputPath = resolvePath(cwd, cmd.inputFile);
+			try {
+				currentOutput = vfs.readFile(inputPath);
+			} catch {
+				return {
+					stderr: `cat: ${cmd.inputFile}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+		}
+
+		// Build raw input
+		const rawInput = [cmd.name, ...cmd.args].join(" ");
+
+		// Create a modified context that might accept stdin
+		// For now, we'll append input as an additional arg for commands that support it
+		const result = await runSingleCommand(
+			rawInput,
+			authUser,
+			hostname,
+			users,
+			mode,
+			cwd,
+			vfs,
+			currentOutput,
+		);
+
+		exitCode = result.exitCode ?? 0;
+
+		// Handle output redirection (only for last command)
+		if (i === commands.length - 1 && cmd.outputFile) {
+			const outputPath = resolvePath(cwd, cmd.outputFile);
+			const output = result.stdout || "";
+			try {
+				if (cmd.appendOutput) {
+					try {
+						const existing = vfs.readFile(outputPath);
+						vfs.writeFile(outputPath, existing + output);
+					} catch {
+						vfs.writeFile(outputPath, output);
+					}
+				} else {
+					vfs.writeFile(outputPath, output);
+				}
+				currentOutput = "";
+			} catch {
+				return {
+					stderr: `Failed to write to ${cmd.outputFile}`,
+					exitCode: 1,
+				};
+			}
+		} else {
+			// Pass output to next command
+			currentOutput = result.stdout || "";
+		}
+
+		if (result.stderr && exitCode !== 0) {
+			return { stderr: result.stderr, exitCode };
+		}
+	}
+
+	return { stdout: currentOutput, exitCode };
+}

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];
+}