typescript-virtual-container 1.2.4 → 1.2.6

package/src/commands/ping.ts

@@ -0,0 +1,20 @@
+import type { ShellModule } from "../types/commands";
+
+export const pingCommand: ShellModule = {
+	name: "ping",
+	description: "Send ICMP ECHO_REQUEST (mock)",
+	category: "network",
+	params: ["[-c <count>] <host>"],
+	run: ({ args }) => {
+		const host = args.find((a) => !a.startsWith("-")) ?? "localhost";
+		const count = 4;
+		const lines = [`PING ${host}: 56 data bytes`];
+		for (let i = 0; i < count; i++) {
+			const ms = (Math.random() * 10 + 1).toFixed(3);
+			lines.push(`64 bytes from ${host}: icmp_seq=${i} ttl=64 time=${ms} ms`);
+		}
+		lines.push(`--- ${host} ping statistics ---`);
+		lines.push(`${count} packets transmitted, ${count} received, 0% packet loss`);
+		return { stdout: lines.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/ps.ts

@@ -0,0 +1,19 @@
+import type { ShellModule } from "../types/commands";
+
+export const psCommand: ShellModule = {
+	name: "ps",
+	description: "Report process status",
+	category: "system",
+	params: ["[-a] [-u] [-x]"],
+	run: ({ authUser, shell }) => {
+		const sessions = shell.users.listActiveSessions();
+		const lines = ["  PID TTY          TIME CMD"];
+		let pid = 1000;
+		for (const s of sessions) {
+			lines.push(`${String(pid).padStart(5)} ${s.tty.padEnd(12)} 00:00:00 ${s.username === authUser ? "bash" : `bash (${s.username})`}`);
+			pid++;
+		}
+		lines.push(`${String(pid).padStart(5)} pts/0        00:00:00 ps`);
+		return { stdout: lines.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/pwd.ts

@@ -2,6 +2,8 @@ import type { ShellModule } from "../types/commands";
 
 export const pwdCommand: ShellModule = {
 	name: "pwd",
+	description: "Print working directory",
+	category: "navigation",
 	params: [],
 	run: ({ cwd }) => ({ stdout: cwd, exitCode: 0 }),
 };

package/src/commands/rm.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const rmCommand: ShellModule = {
 	name: "rm",
+	description: "Remove files or directories",
+	category: "files",
 	params: ["[-r|-rf] <path>"],
 	run: ({ authUser, shell, cwd, args }) => {
 		if (args.length === 0) {

package/src/commands/sed.ts

@@ -0,0 +1,45 @@
+import type { ShellModule } from "../types/commands";
+import { getFlag, ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
+
+export const sedCommand: ShellModule = {
+	name: "sed",
+	description: "Stream editor for filtering and transforming text",
+	category: "text",
+	params: ["-e <expr> [file]", "s/pattern/replace/[g]"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const inPlace = ifFlag(args, ["-i"]);
+		const expr = (getFlag(args, ["-e"]) as string | undefined) ?? args.find((a) => !a.startsWith("-"));
+		const fileArg = args.filter((a) => !a.startsWith("-") && a !== expr).pop();
+
+		if (!expr) return { stderr: "sed: no expression", exitCode: 1 };
+
+		let content = stdin ?? "";
+		if (fileArg) {
+			const p = resolvePath(cwd, fileArg);
+			try { content = shell.vfs.readFile(p); } catch { return { stderr: `sed: ${fileArg}: No such file or directory`, exitCode: 1 }; }
+		}
+
+		// Parse s/from/to/[g]
+		const sMatch = expr.match(/^s([^a-zA-Z0-9])(.+?)\1(.*?)\1([gi]*)$/);
+		if (!sMatch) return { stderr: `sed: unrecognized command: ${expr}`, exitCode: 1 };
+
+		const [, , from, to, flags] = sMatch;
+		const regexFlags = (flags ?? "").includes("i") ? "gi" : (flags ?? "").includes("g") ? "g" : "";
+		let regex: RegExp;
+		try { regex = new RegExp(from!, regexFlags || ""); }
+		catch (_e) { return { stderr: `sed: invalid regex: ${from}`, exitCode: 1 }; }
+
+		const result = (flags ?? "").includes("g") || regexFlags.includes("g")
+			? content.replace(regex, to ?? "")
+			: content.replace(regex, to ?? "");
+
+		if (inPlace && fileArg) {
+			const p = resolvePath(cwd, fileArg);
+			shell.writeFileAsUser(authUser, p, result);
+			return { exitCode: 0 };
+		}
+
+		return { stdout: result, exitCode: 0 };
+	},
+};

package/src/commands/set.ts

@@ -1,10 +1,8 @@
 /** biome-ignore-all lint/style/useNamingConvention: env variables */
 import type { ShellModule } from "../types/commands";
-import { getArg } from "./command-helpers";
 
-// Simple in-memory environment variables store
-// In a real implementation, this would be per-session/per-user
-const envVars: Record<string, string> = {
+// Legacy global store kept for compatibility with older callers
+const _globalEnv: Record<string, string> = {
 	PATH: "/usr/local/bin:/usr/bin:/bin",
 	HOME: "/home/user",
 	SHELL: "/bin/sh",
@@ -12,62 +10,33 @@ const envVars: Record<string, string> = {
 	USER: "user",
 };
 
-export function getEnvVar(name: string): string | undefined {
-	return envVars[name];
-}
-
-export function setEnvVar(name: string, value: string): void {
-	envVars[name] = value;
-}
-
+/** @deprecated use env.vars from CommandContext */
+export function getEnvVar(name: string): string | undefined { return _globalEnv[name]; }
+/** @deprecated use env.vars from CommandContext */
+export function setEnvVar(name: string, value: string): void { _globalEnv[name] = value; }
+/** @deprecated use env.vars from CommandContext */
 export function getAllEnvVars(authUser: string): Record<string, string> {
-	envVars.USER = authUser;
-	envVars.HOME = `/home/${authUser}`;
-	return { ...envVars };
+	_globalEnv.USER = authUser;
+	_globalEnv.HOME = `/home/${authUser}`;
+	return { ..._globalEnv };
 }
 
 export const setCommand: ShellModule = {
 	name: "set",
+	description: "Display or set shell variables",
+	category: "shell",
 	params: ["[VAR=value]"],
-	run: ({ args }) => {
-		// No arguments: display all environment variables
+	run: ({ args, env }) => {
 		if (args.length === 0) {
-			const output = Object.entries(envVars)
-				.map(([key, value]) => `${key}=${value}`)
-				.sort()
-				.join("\n");
-
-			return { stdout: output, exitCode: 0 };
+			const out = Object.entries(env.vars).map(([k, v]) => `${k}=${v}`).join("\n");
+			return { stdout: out, exitCode: 0 };
 		}
-
-		// Parse VAR=value format
-		const assignments: string[] = [];
-		for (let index = 0; ; index += 1) {
-			const arg = getArg(args, index);
-			if (!arg) {
-				break;
-			}
-
+		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`);
-				}
+				const eq = arg.indexOf("=");
+				env.vars[arg.slice(0, eq)] = arg.slice(eq + 1);
 			}
 		}
-
-		return {
-			stdout: assignments.length > 0 ? assignments.join("\n") : "",
-			exitCode: 0,
-		};
+		return { exitCode: 0 };
 	},
 };

package/src/commands/sh.ts

@@ -1,57 +1,206 @@
-import type { CommandContext, ShellModule } from "../types/commands";
-import { getArg, getFlag } from "./command-helpers";
+import type { CommandContext, CommandResult, ShellModule } from "../types/commands";
+import { getArg, ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
 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 { args, authUser, hostname, mode, cwd } = ctx;
-		// Handle -c option: sh -c "command"
-		if (getFlag(args, "-c") && args.length >= 2) {
-			const script = getArg(args, 1) ?? "";
-			if (!script) {
-				return { stderr: "sh: -c requires a script", exitCode: 1 };
+/** Expand $VAR and ${VAR:-default} in a line using the current env */
+function expandVars(line: string, env: Record<string, string>, lastExit: number): string {
+	return line
+		.replace(/\$\?/g, String(lastExit))
+		.replace(/\$\{([^}:]+):-([^}]*)\}/g, (_, n, d) => env[n] ?? d)
+		.replace(/\$\{([^}]+)\}/g, (_, n) => env[n] ?? "")
+		.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, n) => env[n] ?? "")
+		.replace(/^~(\/|$)/, `${env.HOME ?? "/home/user"}$1`);
+}
+
+type Block =
+	| { type: "if"; cond: string; then: string[]; elif: Array<{ cond: string; body: string[] }>; else_: string[] }
+	| { type: "for"; var: string; list: string; body: string[] }
+	| { type: "while"; cond: string; body: string[] }
+	| { type: "cmd"; line: string };
+
+/** Very small shell interpreter: supports if/elif/else/fi, for/do/done, while/do/done */
+function parseBlocks(lines: string[]): Block[] {
+	const blocks: Block[] = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i]!.trim();
+		if (!line || line.startsWith("#")) { i++; continue; }
+
+		if (line.startsWith("if ") || line === "if") {
+			const cond = line.replace(/^if\s+/, "").replace(/;\s*then\s*$/, "").trim();
+			const thenLines: string[] = [];
+			const elifBlocks: Array<{ cond: string; body: string[] }> = [];
+			const elseLines: string[] = [];
+			let section: "then" | "elif" | "else" = "then";
+			let elifCond = "";
+			i++;
+			while (i < lines.length && lines[i]?.trim() !== "fi") {
+				const l = lines[i]!.trim();
+				if (l.startsWith("elif ")) { section = "elif"; elifCond = l.replace(/^elif\s+/, "").replace(/;\s*then\s*$/, "").trim(); elifBlocks.push({ cond: elifCond, body: [] }); }
+				else if (l === "else") { section = "else"; }
+				else if (l !== "then") {
+					if (section === "then") thenLines.push(l);
+					else if (section === "elif" && elifBlocks.length > 0) elifBlocks[elifBlocks.length - 1]!.body.push(l);
+					else elseLines.push(l);
+				}
+				i++;
 			}
-			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 = "";
-			const 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);
+			blocks.push({ type: "if", cond, then: thenLines, elif: elifBlocks, else_: elseLines });
+		} else if (line.startsWith("for ")) {
+			const m = line.match(/^for\s+(\w+)\s+in\s+(.+?)(?:\s*;\s*do)?$/);
+			if (m) {
+				const body: string[] = [];
+				i++;
+				while (i < lines.length && lines[i]?.trim() !== "done") {
+					const l = lines[i]!.trim();
+					if (l !== "do") body.push(l);
+					i++;
 				}
-				command = command.replaceAll("$@", scriptArgs.join(" "));
+				blocks.push({ type: "for", var: m[1]!, list: m[2]!, body });
+			} else { blocks.push({ type: "cmd", line }); }
+		} else if (line.startsWith("while ")) {
+			const cond = line.replace(/^while\s+/, "").replace(/;\s*do\s*$/, "").trim();
+			const body: string[] = [];
+			i++;
+			while (i < lines.length && lines[i]?.trim() !== "done") {
+				const l = lines[i]!.trim();
+				if (l !== "do") body.push(l);
+				i++;
+			}
+			blocks.push({ type: "while", cond, body });
+		} else {
+			blocks.push({ type: "cmd", line });
+		}
+		i++;
+	}
+	return blocks;
+}
 
-				// Execute the command
-				const result = await Promise.resolve(
-					runCommand(command, authUser, hostname, mode, cwd, ctx.shell),
-				);
+async function evalCondition(cond: string, ctx: CommandContext): Promise<boolean> {
+	const expanded = expandVars(cond, ctx.env.vars, ctx.env.lastExitCode);
+	// test -f / test -d / [ ... ]
+	const testMatch = expanded.match(/^\[?\s*(.+?)\s*\]?$/);
+	if (testMatch) {
+		const expr = testMatch[1]!;
+		// -f file
+		const fTest = expr.match(/^-([fdeznr])\s+(.+)$/);
+		if (fTest) {
+			const [, flag, arg] = fTest;
+			const p = resolvePath(ctx.cwd, arg!);
+			if (flag === "f") return ctx.shell.vfs.exists(p) && ctx.shell.vfs.stat(p).type === "file";
+			if (flag === "d") return ctx.shell.vfs.exists(p) && ctx.shell.vfs.stat(p).type === "directory";
+			if (flag === "e") return ctx.shell.vfs.exists(p);
+			if (flag === "z") return (arg ?? "").length === 0;
+			if (flag === "n") return (arg ?? "").length > 0;
+		}
+		// string comparison
+		const cmpMatch = expr.match(/^"?([^"]*)"?\s*(==|!=|=|<|>)\s*"?([^"]*)"?$/);
+		if (cmpMatch) {
+			const [, a, op, b] = cmpMatch;
+			if (op === "==" || op === "=") return a === b;
+			if (op === "!=") return a !== b;
+		}
+		// numeric
+		const numMatch = expr.match(/^(\S+)\s+(-eq|-ne|-lt|-le|-gt|-ge)\s+(\S+)$/);
+		if (numMatch) {
+			const [, a, op, b] = numMatch;
+			const na = Number(a), nb = Number(b);
+			if (op === "-eq") return na === nb;
+			if (op === "-ne") return na !== nb;
+			if (op === "-lt") return na < nb;
+			if (op === "-le") return na <= nb;
+			if (op === "-gt") return na > nb;
+			if (op === "-ge") return na >= nb;
+		}
+	}
+	// fallback: run command and check exit code
+	const r = await runCommand(expanded, ctx.authUser, ctx.hostname, ctx.mode, ctx.cwd, ctx.shell, undefined, ctx.env);
+	return (r.exitCode ?? 0) === 0;
+}
 
-				if (result.stdout) {
-					output += `${result.stdout}\n`;
-				}
+async function runBlocks(blocks: Block[], ctx: CommandContext): Promise<CommandResult> {
+	let lastResult: CommandResult = { exitCode: 0 };
+	let output = "";
 
-				if (result.stderr) {
-					return { stderr: result.stderr, exitCode: result.exitCode ?? 1 };
+	for (const block of blocks) {
+		if (block.type === "cmd") {
+			const expanded = expandVars(block.line, ctx.env.vars, ctx.env.lastExitCode);
+			const r = await runCommand(expanded, ctx.authUser, ctx.hostname, ctx.mode, ctx.cwd, ctx.shell, undefined, ctx.env);
+			ctx.env.lastExitCode = r.exitCode ?? 0;
+			if (r.stdout) output += `${r.stdout}\n`;
+			if (r.stderr) return { ...r, stdout: output.trim() };
+			lastResult = r;
+		} else if (block.type === "if") {
+			let ran = false;
+			if (await evalCondition(block.cond, ctx)) {
+				const sub = await runBlocks(parseBlocks(block.then), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				ran = true;
+			} else {
+				for (const elif of block.elif) {
+					if (await evalCondition(elif.cond, ctx)) {
+						const sub = await runBlocks(parseBlocks(elif.body), ctx);
+						if (sub.stdout) output += `${sub.stdout}\n`;
+						ran = true; break;
+					}
+				}
+				if (!ran && block.else_.length > 0) {
+					const sub = await runBlocks(parseBlocks(block.else_), ctx);
+					if (sub.stdout) output += `${sub.stdout}\n`;
 				}
 			}
+		} else if (block.type === "for") {
+			const listExpanded = expandVars(block.list, ctx.env.vars, ctx.env.lastExitCode);
+			const items = listExpanded.trim().split(/\s+/);
+			for (const item of items) {
+				ctx.env.vars[block.var] = item;
+				const sub = await runBlocks(parseBlocks(block.body), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				if (sub.closeSession) return sub;
+			}
+		} else if (block.type === "while") {
+			let iterations = 0;
+			while (iterations < 1000 && await evalCondition(block.cond, ctx)) {
+				const sub = await runBlocks(parseBlocks(block.body), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				if (sub.closeSession) return sub;
+				iterations++;
+			}
+		}
+	}
+	return { ...lastResult, stdout: output.trim() || lastResult.stdout };
+}
+
+export const shCommand: ShellModule = {
+	name: "sh",
+	aliases: ["bash"],
+	description: "Execute shell script or command",
+	category: "shell",
+	params: ["-c <script>", "[<file>]"],
+	run: async (ctx: CommandContext) => {
+		const { args, authUser, shell, cwd } = ctx;
+
+		// sh -c "inline script"
+		if (ifFlag(args, "-c")) {
+			const script = getArg(args, 1) ?? "";
+			if (!script) return { stderr: "sh: -c requires a script", exitCode: 1 };
+			const lines = script.split(/[;\n]/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+			const blocks = parseBlocks(lines);
+			return runBlocks(blocks, ctx);
+		}
 
-			return { stdout: output.trim(), exitCode };
+		// sh <file>
+		const fileArg = args[0];
+		if (fileArg) {
+			const p = resolvePath(cwd, fileArg);
+			if (!shell.vfs.exists(p)) return { stderr: `sh: ${fileArg}: No such file or directory`, exitCode: 1 };
+			const content = shell.vfs.readFile(p);
+			const lines = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+			const blocks = parseBlocks(lines);
+			return runBlocks(blocks, ctx);
 		}
 
-		return { stderr: "sh: invalid usage", exitCode: 1 };
+		return { stderr: "sh: invalid usage. Use: sh -c 'cmd' or sh <file>", exitCode: 1 };
 	},
 };

package/src/commands/sleep.ts

@@ -0,0 +1,14 @@
+import type { ShellModule } from "../types/commands";
+
+export const sleepCommand: ShellModule = {
+	name: "sleep",
+	description: "Delay execution",
+	category: "system",
+	params: ["<seconds>"],
+	run: async ({ args }) => {
+		const secs = parseFloat(args[0] ?? "1");
+		if (Number.isNaN(secs) || secs < 0) return { stderr: "sleep: invalid time", exitCode: 1 };
+		await new Promise((r) => setTimeout(r, secs * 1000));
+		return { exitCode: 0 };
+	},
+};

package/src/commands/sort.ts

@@ -0,0 +1,37 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const sortCommand: ShellModule = {
+	name: "sort",
+	description: "Sort lines of text",
+	category: "text",
+	params: ["[-r] [-n] [-u] [-k <col>] [file...]"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const reverse = ifFlag(args, ["-r"]);
+		const numeric = ifFlag(args, ["-n"]);
+		const unique = ifFlag(args, ["-u"]);
+		const files = args.filter((a) => !a.startsWith("-"));
+
+		const getContent = (): string => {
+			if (files.length > 0) {
+				return files.map((f) => {
+					try {
+						assertPathAccess(authUser, resolvePath(cwd, f), "sort");
+						return shell.vfs.readFile(resolvePath(cwd, f));
+					} catch { return ""; }
+				}).join("\n");
+			}
+			return stdin ?? "";
+		};
+
+		const lines = getContent().split("\n").filter(Boolean);
+		const sorted = [...lines].sort((a, b) => {
+			if (numeric) return Number(a) - Number(b);
+			return a.localeCompare(b);
+		});
+		const result = reverse ? sorted.reverse() : sorted;
+		const out = unique ? [...new Set(result)] : result;
+		return { stdout: out.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/su.ts

@@ -3,6 +3,8 @@ import { getArg } from "./command-helpers";
 
 export const suCommand: ShellModule = {
 	name: "su",
+	description: "Switch user",
+	category: "users",
 	params: ["- <username>"],
 	run: ({ authUser, shell, args }) => {
 		const users = shell.users!;

package/src/commands/sudo.ts

@@ -21,6 +21,8 @@ function parseSudoArgs(args: string[]): {
 }
 export const sudoCommand: ShellModule = {
 	name: "sudo",
+	description: "Execute as superuser",
+	category: "users",
 	params: ["<command...>"],
 	run: async ({ authUser, hostname, mode, cwd, shell, args }) => {
 		const { targetUser, loginShell, commandLine } = parseSudoArgs(args);

package/src/commands/tail.ts

@@ -0,0 +1,39 @@
+import type { ShellModule } from "../types/commands";
+import { getFlag } from "./command-helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const tailCommand: ShellModule = {
+	name: "tail",
+	description: "Output last lines",
+	category: "text",
+	params: ["[-n <lines>] [file...]"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const nArg = getFlag(args, ["-n"]);
+		const n = typeof nArg === "string" ? parseInt(nArg, 10) : 10;
+		const positionals = args.filter((a) => !a.startsWith("-") && a !== nArg);
+
+		const take = (content: string) => {
+			const lines = content.split("\n");
+			return lines.slice(Math.max(0, lines.length - n)).join("\n");
+		};
+
+		if (positionals.length === 0) {
+			return { stdout: take(stdin ?? ""), exitCode: 0 };
+		}
+
+		const results: string[] = [];
+		for (const file of positionals) {
+			const filePath = resolvePath(cwd, file);
+			try {
+				assertPathAccess(authUser, filePath, "tail");
+				results.push(take(shell.vfs.readFile(filePath)));
+			} catch {
+				return {
+					stderr: `tail: ${file}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+		}
+		return { stdout: results.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/tar.ts

@@ -0,0 +1,58 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
+
+export const tarCommand: ShellModule = {
+	name: "tar",
+	description: "Archive utility",
+	category: "archive",
+	params: ["[-czf|-xzf|-tf] <archive> [files...]"],
+	run: ({ authUser, shell, cwd, args }) => {
+		const create = ifFlag(args, ["-c"]);
+		const extract = ifFlag(args, ["-x"]);
+		const list = ifFlag(args, ["-t"]);
+		const fFlag = args.findIndex((a) => a.includes("f"));
+		const archiveName = fFlag !== -1 ? args[fFlag + 1] : args.find((a) => a.endsWith(".tar") || a.endsWith(".tar.gz") || a.endsWith(".tgz"));
+
+		if (!archiveName) return { stderr: "tar: no archive specified", exitCode: 1 };
+		const archivePath = resolvePath(cwd, archiveName);
+
+		if (create) {
+			const fileArgs = args.filter((a) => !a.startsWith("-") && a !== archiveName);
+			const entries: Record<string, string> = {};
+			for (const f of fileArgs) {
+				const p = resolvePath(cwd, f);
+				try {
+					const stat = shell.vfs.stat(p);
+					if (stat.type === "file") entries[f] = shell.vfs.readFile(p);
+					else {
+						const walk = (dir: string, prefix: string) => {
+							for (const e of shell.vfs.list(dir)) {
+								const full = `${dir}/${e}`, rel = `${prefix}/${e}`;
+								const s = shell.vfs.stat(full);
+								if (s.type === "file") entries[rel] = shell.vfs.readFile(full);
+								else walk(full, rel);
+							}
+						};
+						walk(p, f);
+					}
+				} catch { return { stderr: `tar: ${f}: No such file or directory`, exitCode: 1 }; }
+			}
+			shell.writeFileAsUser(authUser, archivePath, JSON.stringify(entries));
+			return { exitCode: 0 };
+		}
+
+		if (list || extract) {
+			let entries: Record<string, string>;
+			try { entries = JSON.parse(shell.vfs.readFile(archivePath)); }
+			catch { return { stderr: `tar: ${archiveName}: cannot open archive`, exitCode: 1 }; }
+			if (list) return { stdout: Object.keys(entries).join("\n"), exitCode: 0 };
+			for (const [name, content] of Object.entries(entries)) {
+				shell.writeFileAsUser(authUser, resolvePath(cwd, name), content);
+			}
+			return { exitCode: 0 };
+		}
+
+		return { stderr: "tar: must specify -c, -x, or -t", exitCode: 1 };
+	},
+};

package/src/commands/tee.ts

@@ -0,0 +1,25 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
+
+export const teeCommand: ShellModule = {
+	name: "tee",
+	description: "Read stdin, write to stdout and files",
+	category: "text",
+	params: ["[-a] <file...>"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const append = ifFlag(args, ["-a"]);
+		const files = args.filter((a) => !a.startsWith("-"));
+		const input = stdin ?? "";
+		for (const f of files) {
+			const p = resolvePath(cwd, f);
+			if (append) {
+				const existing = (() => { try { return shell.vfs.readFile(p); } catch { return ""; } })();
+				shell.writeFileAsUser(authUser, p, existing + input);
+			} else {
+				shell.writeFileAsUser(authUser, p, input);
+			}
+		}
+		return { stdout: input, exitCode: 0 };
+	},
+};

package/src/commands/touch.ts

@@ -3,6 +3,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const touchCommand: ShellModule = {
 	name: "touch",
+	description: "Create or update files",
+	category: "files",
 	params: ["<file>"],
 	run: ({ authUser, shell, cwd, args }) => {
 		if (args.length === 0) {