typescript-virtual-container 1.0.3 → 1.0.4

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,37 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [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
 
@@ -1006,7 +1006,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 +1125,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 +1262,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.4",
   "license": "MIT",
   "keywords": [
     "ssh",

package/src/SSHMimic/commands/echo.ts

@@ -0,0 +1,26 @@
+import type { ShellModule } from "../../types/commands";
+import { getAllEnvVars } from "./set";
+
+function expandEnvVars(input: string, env: Record<string, string>): string {
+	return input.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name: string) => {
+		return env[name] ?? "";
+	});
+}
+
+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 env = getAllEnvVars(authUser);
+		const rawText =
+			filteredArgs.length > 0 ? filteredArgs.join(" ") : (stdin ?? "");
+		const text = expandEnvVars(rawText, env);
+
+		return {
+			stdout: newline ? text : text.trimEnd(),
+			exitCode: 0,
+		};
+	},
+};

package/src/SSHMimic/commands/env.ts

@@ -0,0 +1,22 @@
+import type { ShellModule } from "../../types/commands";
+import { getAllEnvVars } from "./set";
+
+export const envCommand: ShellModule = {
+	name: "env",
+	params: ["[VAR=value...] [command]"],
+	run: ({ authUser }) => {
+		// For now, just display all environment variables
+		// In a full implementation, this would also handle running commands with modified env
+
+		const allVars = getAllEnvVars(authUser);
+		const envVarsOutput = Object.entries(allVars)
+			.map(([key, value]) => `${key}=${value}`)
+			.sort()
+			.join("\n");
+
+		return {
+			stdout: envVarsOutput,
+			exitCode: 0,
+		};
+	},
+};

package/src/SSHMimic/commands/export.ts

@@ -0,0 +1,32 @@
+import type { ShellModule } from "../../types/commands";
+import { getEnvVar, setEnvVar } from "./set";
+
+export const exportCommand: ShellModule = {
+	name: "export",
+	params: ["[VAR=value]"],
+	run: ({ args }) => {
+		// export VAR=value or export VAR (to make it available to child processes)
+		if (args.length === 0) {
+			// List all exported variables
+			return {
+				stdout: "# export command - sets variables for child processes",
+				exitCode: 0,
+			};
+		}
+
+		// Parse VAR=value format
+		for (const arg of args) {
+			if (arg.includes("=")) {
+				const [varName, varValue] = arg.split("=", 2);
+				if (varName && varValue !== undefined) {
+					setEnvVar(varName, varValue);
+				}
+			} else {
+				// export VAR_NAME makes it available but we just set it
+				setEnvVar(arg, getEnvVar(arg) || "");
+			}
+		}
+
+		return { exitCode: 0 };
+	},
+};

package/src/SSHMimic/commands/grep.ts

@@ -0,0 +1,81 @@
+import type { ShellModule } from "../../types/commands";
+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");
+
+		if (filteredArgs.length === 0) {
+			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);
+		} catch {
+			return { stderr: `grep: invalid regex: ${pattern}`, exitCode: 1 };
+		}
+
+		const results: string[] = [];
+
+		// If no files specified, read from stdin (pipe/input redirection).
+		if (files.length === 0) {
+			if (!stdin) {
+				return { stdout: "", exitCode: 1 };
+			}
+
+			const lines = stdin.split("\n");
+			for (const line of lines) {
+				regex.lastIndex = 0;
+				const matches = regex.test(line);
+				const shouldInclude = invertMatch ? !matches : matches;
+
+				if (shouldInclude) {
+					results.push(line);
+				}
+			}
+
+			return {
+				stdout: results.length > 0 ? results.join("\n") : "",
+				exitCode: results.length > 0 ? 0 : 1,
+			};
+		}
+
+		for (const file of files) {
+			const target = resolvePath(cwd, file);
+			try {
+				assertPathAccess(authUser, target, "grep");
+				const content = vfs.readFile(target);
+				const lines = content.split("\n");
+
+				for (const line of lines) {
+					regex.lastIndex = 0;
+					const matches = regex.test(line);
+					const shouldInclude = invertMatch ? !matches : matches;
+
+					if (shouldInclude) {
+						results.push(line);
+					}
+				}
+			} catch {
+				return {
+					stderr: `grep: ${file}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+		}
+
+		return {
+			stdout: results.length > 0 ? results.join("\n") : "",
+			exitCode: results.length > 0 ? 0 : 1,
+		};
+	},
+};

package/src/SSHMimic/commands/index.ts

@@ -1,6 +1,7 @@
 import type {
 	CommandMode,
 	CommandOutcome,
+	CommandResult,
 	ShellModule,
 } from "../../types/commands";
 import type VirtualFileSystem from "../../VirtualFileSystem";
@@ -11,7 +12,11 @@ import { cdCommand } from "./cd";
 import { clearCommand } from "./clear";
 import { curlCommand } from "./curl";
 import { deluserCommand } from "./deluser";
+import { echoCommand } from "./echo";
+import { envCommand } from "./env";
 import { exitCommand } from "./exit";
+import { exportCommand } from "./export";
+import { grepCommand } from "./grep";
 import { createHelpCommand } from "./help";
 import { hostnameCommand } from "./hostname";
 import { htopCommand } from "./htop";
@@ -20,10 +25,13 @@ import { mkdirCommand } from "./mkdir";
 import { nanoCommand } from "./nano";
 import { pwdCommand } from "./pwd";
 import { rmCommand } from "./rm";
+import { setCommand } from "./set";
+import { shCommand } from "./sh";
 import { suCommand } from "./su";
 import { sudoCommand } from "./sudo";
 import { touchCommand } from "./touch";
 import { treeCommand } from "./tree";
+import { unsetCommand } from "./unset";
 import { wgetCommand } from "./wget";
 import { whoCommand } from "./who";
 import { whoamiCommand } from "./whoami";
@@ -36,6 +44,7 @@ const BASE_COMMANDS: ShellModule[] = [
 	lsCommand,
 	cdCommand,
 	catCommand,
+	echoCommand,
 	mkdirCommand,
 	touchCommand,
 	rmCommand,
@@ -47,7 +56,13 @@ const BASE_COMMANDS: ShellModule[] = [
 	sudoCommand,
 	suCommand,
 	curlCommand,
+	envCommand,
 	wgetCommand,
+	grepCommand,
+	exportCommand,
+	setCommand,
+	unsetCommand,
+	shCommand,
 	clearCommand,
 	exitCommand,
 ];
@@ -68,14 +83,134 @@ function resolveModule(name: string): ShellModule | undefined {
 	);
 }
 
+function splitArgsRespectingQuotes(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let quoteChar = "";
+
+	for (let i = 0; i < input.length; i += 1) {
+		const ch = input[i] || "";
+		const prev = i > 0 ? input[i - 1] : "";
+
+		if ((ch === '"' || ch === "'") && prev !== "\\") {
+			if (!inQuotes) {
+				inQuotes = true;
+				quoteChar = ch;
+				continue;
+			}
+
+			if (ch === quoteChar) {
+				inQuotes = false;
+				quoteChar = "";
+				continue;
+			}
+		}
+
+		if (/\s/.test(ch) && !inQuotes) {
+			if (current.length > 0) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+
+		current += ch;
+	}
+
+	if (current.length > 0) {
+		tokens.push(current);
+	}
+
+	return tokens;
+}
+
 function parseInput(rawInput: string): { commandName: string; args: string[] } {
-	const parts = rawInput.trim().split(/\s+/).filter(Boolean);
+	const parts = splitArgsRespectingQuotes(rawInput.trim());
 	return {
 		commandName: parts[0]?.toLowerCase() ?? "",
 		args: parts.slice(1),
 	};
 }
 
+// Internal async function for pipeline execution
+async function runCommandInternal(
+	rawInput: string,
+	authUser: string,
+	hostname: string,
+	users: VirtualUserManager,
+	mode: CommandMode,
+	cwd: string,
+	vfs: VirtualFileSystem,
+	stdin?: string,
+): Promise<CommandResult> {
+	// Check if input contains pipes or redirections
+	if (
+		rawInput.includes("|") ||
+		rawInput.includes(">") ||
+		rawInput.includes("<")
+	) {
+		// Use pipeline executor
+		const { parseShellPipeline } = await import("../shellParser");
+		const { executePipeline } = await import("../executor");
+
+		const pipeline = parseShellPipeline(rawInput);
+		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 command execution
+	const { commandName, args } = parseInput(rawInput);
+	const mod = resolveModule(commandName);
+
+	if (!mod) {
+		return {
+			stderr: `Command '${rawInput}' not found`,
+			exitCode: 127,
+		};
+	}
+
+	try {
+		const result = mod.run({
+			authUser,
+			hostname,
+			users,
+			activeSessions: users.listActiveSessions(),
+			rawInput,
+			mode,
+			args,
+			stdin,
+			cwd,
+			vfs,
+		});
+
+		return await Promise.resolve(result);
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : "Command failed";
+		return { stderr: message, exitCode: 1 };
+	}
+}
+
 export function runCommand(
 	rawInput: string,
 	authUser: string,
@@ -84,6 +219,7 @@ export function runCommand(
 	mode: CommandMode,
 	cwd: string,
 	vfs: VirtualFileSystem,
+	stdin?: string,
 ): CommandOutcome {
 	const trimmed = rawInput.trim();
 
@@ -91,6 +227,21 @@ export function runCommand(
 		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,
+			vfs,
+			stdin,
+		);
+	}
+
+	// Regular synchronous command execution
 	const { commandName, args } = parseInput(trimmed);
 	const mod = resolveModule(commandName);
 
@@ -110,6 +261,7 @@ export function runCommand(
 			rawInput: trimmed,
 			mode,
 			args,
+			stdin,
 			cwd,
 			vfs,
 		});

package/src/SSHMimic/commands/set.ts

@@ -0,0 +1,67 @@
+/** biome-ignore-all lint/style/useNamingConvention: env variables */
+import type { ShellModule } from "../../types/commands";
+
+// Simple in-memory environment variables store
+// In a real implementation, this would be per-session/per-user
+const envVars: Record<string, string> = {
+	PATH: "/usr/local/bin:/usr/bin:/bin",
+	HOME: "/home/user",
+	SHELL: "/bin/sh",
+	TERM: "xterm-256color",
+	USER: "user",
+};
+
+export function getEnvVar(name: string): string | undefined {
+	return envVars[name];
+}
+
+export function setEnvVar(name: string, value: string): void {
+	envVars[name] = value;
+}
+
+export function getAllEnvVars(authUser: string): Record<string, string> {
+	envVars.USER = authUser;
+	envVars.HOME = `/home/${authUser}`;
+	return { ...envVars };
+}
+
+export const setCommand: ShellModule = {
+	name: "set",
+	params: ["[VAR=value]"],
+	run: ({ args }) => {
+		// No arguments: display all environment variables
+		if (args.length === 0) {
+			const output = Object.entries(envVars)
+				.map(([key, value]) => `${key}=${value}`)
+				.sort()
+				.join("\n");
+
+			return { stdout: output, exitCode: 0 };
+		}
+
+		// Parse VAR=value format
+		const assignments: string[] = [];
+		for (const arg of args) {
+			if (arg.includes("=")) {
+				const [varName, varValue] = arg.split("=", 2);
+				if (varName && varValue !== undefined) {
+					setEnvVar(varName, varValue);
+					assignments.push(arg);
+				}
+			} else {
+				// If no '=' present, display that specific variable
+				const value = getEnvVar(arg);
+				if (value !== undefined) {
+					assignments.push(`${arg}=${value}`);
+				} else {
+					assignments.push(`${arg}: not set`);
+				}
+			}
+		}
+
+		return {
+			stdout: assignments.length > 0 ? assignments.join("\n") : "",
+			exitCode: 0,
+		};
+	},
+};

package/src/SSHMimic/commands/sh.ts

@@ -0,0 +1,121 @@
+import type { CommandContext, ShellModule } from "../../types/commands";
+import { runCommand } from "./index";
+
+/** Simple shell script executor with basic variable support */
+export const shCommand: ShellModule = {
+	name: "sh",
+	params: ["-c <script>", "[<file>]"],
+	aliases: ["bash"],
+	run: async (ctx: CommandContext) => {
+		const { vfs, args, authUser, hostname, users, mode, cwd } = ctx;
+
+		// Handle -c option: sh -c "command"
+		if (args[0] === "-c" && args.length >= 2) {
+			const script = args[1] ?? "";
+			if (!script) {
+				return { stderr: "sh: -c requires a script", exitCode: 1 };
+			}
+			const scriptArgs = args.slice(2);
+
+			// Split by semicolon and newline
+			const lines = script
+				.split(/[;\n]/)
+				.map((line) => line.trim())
+				.filter((line) => line && !line.startsWith("#"));
+
+			let output = "";
+			let exitCode = 0;
+
+			for (const line of lines) {
+				// Simple variable substitution
+				let command = line;
+				for (let i = 0; i < scriptArgs.length; i++) {
+					const arg = scriptArgs[i] ?? "";
+					command = command.replaceAll(`$${i}`, arg);
+				}
+				command = command.replaceAll("$@", scriptArgs.join(" "));
+
+				// Execute the command
+				const result = await Promise.resolve(
+					runCommand(command, authUser, hostname, users, mode, cwd, vfs),
+				);
+
+				if (result.stdout) {
+					output += `${result.stdout}\n`;
+				}
+
+				if (result.stderr) {
+					return { stderr: result.stderr, exitCode: result.exitCode ?? 1 };
+				}
+
+				exitCode = result.exitCode ?? 0;
+				if (exitCode !== 0) {
+					break;
+				}
+			}
+
+			return {
+				stdout: output.trimEnd(),
+				exitCode,
+			};
+		}
+
+		// Handle script file execution: sh <file>
+		if (args.length > 0 && args[0]) {
+			try {
+				const scriptFile = args[0];
+				const content = vfs.readFile(scriptFile);
+				const scriptArgs = args.slice(1);
+
+				// Split by newline
+				const lines = content
+					.split("\n")
+					.map((line) => line.trim())
+					.filter((line) => line && !line.startsWith("#"));
+
+				let output = "";
+				let exitCode = 0;
+
+				for (const line of lines) {
+					// Simple variable substitution
+					let command = line;
+					for (let i = 0; i < scriptArgs.length; i++) {
+						const arg = scriptArgs[i] ?? "";
+						command = command.replaceAll(`$${i}`, arg);
+					}
+					command = command.replaceAll("$@", scriptArgs.join(" "));
+
+					// Execute the command
+					const result = await Promise.resolve(
+						runCommand(command, authUser, hostname, users, mode, cwd, vfs),
+					);
+
+					if (result.stdout) {
+						output += `${result.stdout}\n`;
+					}
+
+					if (result.stderr) {
+						return { stderr: result.stderr, exitCode: result.exitCode ?? 1 };
+					}
+
+					exitCode = result.exitCode ?? 0;
+					if (exitCode !== 0) {
+						break;
+					}
+				}
+
+				return {
+					stdout: output.trimEnd(),
+					exitCode,
+				};
+			} catch {
+				return {
+					stderr: `sh: ${args[0]}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+		}
+
+		return { stderr: "sh: missing operand or script", exitCode: 1 };
+	},
+};

package/src/SSHMimic/commands/unset.ts

@@ -0,0 +1,19 @@
+import type { ShellModule } from "../../types/commands";
+import { setEnvVar } from "./set";
+
+export const unsetCommand: ShellModule = {
+	name: "unset",
+	params: ["<VAR...>"],
+	run: ({ args }) => {
+		if (args.length === 0) {
+			return { stderr: "unset: missing variable name", exitCode: 1 };
+		}
+
+		// Unset (remove) all specified variables
+		for (const varName of args) {
+			setEnvVar(varName, "");
+		}
+
+		return { exitCode: 0 };
+	},
+};

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 "./commands";
+import { resolvePath } from "./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/shellParser.ts

@@ -0,0 +1,203 @@
+import type { Pipeline, PipelineCommand } from "../types/pipeline";
+
+/** Parse a shell command line into a structured pipeline */
+export function parseShellPipeline(rawInput: string): Pipeline {
+	const trimmed = rawInput.trim();
+
+	if (!trimmed) {
+		return { commands: [], isValid: true };
+	}
+
+	const commands: PipelineCommand[] = [];
+	const pipeTokens = tokenizePipeline(trimmed);
+
+	for (const token of pipeTokens) {
+		const cmd = parseCommandWithRedirections(token);
+		if (!cmd.isValid) {
+			return {
+				commands: [],
+				isValid: false,
+				error: cmd.error,
+			};
+		}
+		if (cmd.command) {
+			commands.push(cmd.command);
+		}
+	}
+
+	return { commands, isValid: true };
+}
+
+/** Tokenize input by pipes, respecting quoted strings */
+function tokenizePipeline(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let quoteChar = "";
+	let i = 0;
+
+	while (i < input.length) {
+		const ch = input[i];
+
+		if ((ch === '"' || ch === "'") && (i === 0 || input[i - 1] !== "\\")) {
+			if (!inQuotes) {
+				inQuotes = true;
+				quoteChar = ch;
+			} else if (ch === quoteChar) {
+				inQuotes = false;
+			}
+			current += ch;
+			i++;
+		} else if (ch === "|" && !inQuotes) {
+			if (current.trim()) {
+				tokens.push(current.trim());
+			}
+			current = "";
+			i++;
+		} else {
+			current += ch;
+			i++;
+		}
+	}
+
+	if (current.trim()) {
+		tokens.push(current.trim());
+	}
+
+	return tokens;
+}
+
+interface ParseResult {
+	command?: PipelineCommand;
+	isValid: boolean;
+	error?: string;
+}
+
+/** Parse a single command with its redirections (>, >>, <) */
+function parseCommandWithRedirections(token: string): ParseResult {
+	const parts = tokenizeCommand(token);
+
+	if (parts.length === 0) {
+		return { isValid: true };
+	}
+
+	const cmdParts: string[] = [];
+	let inputFile: string | undefined;
+	let outputFile: string | undefined;
+	let appendOutput = false;
+
+	let i = 0;
+	while (i < parts.length) {
+		const part = parts[i] as string;
+
+		if (part === "<") {
+			i++;
+			if (i >= parts.length) {
+				return {
+					isValid: false,
+					error: "Syntax error: expected filename after <",
+				};
+			}
+			inputFile = parts[i];
+			i++;
+		} else if (part === ">>") {
+			i++;
+			if (i >= parts.length) {
+				return {
+					isValid: false,
+					error: "Syntax error: expected filename after >>",
+				};
+			}
+			outputFile = parts[i];
+			appendOutput = true;
+			i++;
+		} else if (part === ">") {
+			i++;
+			if (i >= parts.length) {
+				return {
+					isValid: false,
+					error: "Syntax error: expected filename after >",
+				};
+			}
+			outputFile = parts[i];
+			appendOutput = false;
+			i++;
+		} else {
+			cmdParts.push(part);
+			i++;
+		}
+	}
+
+	if (cmdParts.length === 0) {
+		return { isValid: true };
+	}
+
+	const name = (cmdParts[0] as string).toLowerCase();
+	const args = cmdParts.slice(1);
+
+	return {
+		command: {
+			name,
+			args,
+			inputFile,
+			outputFile,
+			appendOutput,
+		},
+		isValid: true,
+	};
+}
+
+/** Tokenize a command, respecting quotes and handling >> vs > */
+function tokenizeCommand(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let quoteChar = "";
+	let i = 0;
+
+	while (i < input.length) {
+		const ch = input[i];
+		const next = input[i + 1];
+
+		// Handle quotes
+		if ((ch === '"' || ch === "'") && (i === 0 || input[i - 1] !== "\\")) {
+			if (!inQuotes) {
+				inQuotes = true;
+				quoteChar = ch;
+			} else if (ch === quoteChar) {
+				inQuotes = false;
+				quoteChar = "";
+			} else {
+				current += ch;
+			}
+			i++;
+		} else if (ch === " " && !inQuotes) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			i++;
+		} else if ((ch === ">" || ch === "<") && !inQuotes) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			if (ch === ">" && next === ">") {
+				tokens.push(">>");
+				i += 2;
+			} else {
+				tokens.push(ch);
+				i++;
+			}
+		} else {
+			current += ch;
+			i++;
+		}
+	}
+
+	if (current) {
+		tokens.push(current);
+	}
+
+	return tokens;
+}

package/src/types/commands.ts

@@ -76,6 +76,8 @@ export interface CommandContext {
 	mode: CommandMode;
 	/** Tokenized arguments excluding command name. */
 	args: string[];
+	/** Optional stdin payload (used by pipes/redirections). */
+	stdin?: string;
 	/** Current working directory for command execution. */
 	cwd: string;
 	/** Virtual filesystem instance for IO operations. */

package/src/types/pipeline.ts

@@ -0,0 +1,23 @@
+/** Represents a single command in a pipeline. */
+export interface PipelineCommand {
+	/** Command name */
+	name: string;
+	/** Command arguments */
+	args: string[];
+	/** Input redirection file path (< file) */
+	inputFile?: string;
+	/** Output redirection file path (> file) */
+	outputFile?: string;
+	/** Append to output file (>> file) */
+	appendOutput?: boolean;
+}
+
+/** Represents a parsed shell pipeline */
+export interface Pipeline {
+	/** List of commands in the pipeline */
+	commands: PipelineCommand[];
+	/** Whether this is a valid pipeline */
+	isValid: boolean;
+	/** Error message if parsing failed */
+	error?: string;
+}