typescript-virtual-container 1.2.4 → 1.2.6

package/src/commands/help.ts

@@ -1,9 +1,87 @@
 import type { ShellModule } from "../types/commands";
+import { getCommandModulesPublic } from "./index";
 
-export function createHelpCommand(getNames: () => string[]): ShellModule {
+const CATEGORY_ORDER = ["navigation", "files", "text", "archive", "system", "network", "shell", "users", "misc"];
+const CATEGORY_LABELS: Record<string, string> = {
+	navigation: "Navigation",
+	files: "Files & Filesystem",
+	text: "Text Processing",
+	archive: "Archive & Compression",
+	system: "System",
+	network: "Network",
+	shell: "Shell",
+	users: "Users & Permissions",
+	misc: "Miscellaneous",
+};
+
+function padRight(s: string, n: number): string {
+	return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+export function createHelpCommand(_getNames: () => string[]): ShellModule {
 	return {
 		name: "help",
-		params: [],
-		run: () => ({ stdout: `Builtins: ${getNames().join(" ")}`, exitCode: 0 }),
+		description: "Display this help message",
+		category: "shell",
+		params: ["[command]"],
+		run: ({ args }) => {
+			const modules = getCommandModulesPublic();
+
+			// help <command>
+			if (args[0]) {
+				const mod = modules.find((m) => m.name === args[0] || m.aliases?.includes(args[0]!));
+				if (!mod) return { stderr: `help: no help for '${args[0]}'`, exitCode: 1 };
+				const aliases = mod.aliases?.length ? `  aliases: ${mod.aliases.join(", ")}\n` : "";
+				const params = mod.params.map((p) => `  ${mod.name} ${p}`).join("\n");
+				return {
+					stdout: [
+						`\x1b[1m${mod.name}\x1b[0m — ${mod.description ?? "no description"}`,
+						aliases,
+						"Usage:",
+						params || `  ${mod.name}`,
+					].filter(Boolean).join("\n"),
+					exitCode: 0,
+				};
+			}
+
+			// Full help — grouped by category
+			const grouped: Record<string, ShellModule[]> = {};
+			for (const mod of modules) {
+				const cat = mod.category ?? "misc";
+				if (!grouped[cat]) grouped[cat] = [];
+				grouped[cat]!.push(mod);
+			}
+
+			const lines: string[] = [];
+			lines.push("\x1b[1mAvailable commands\x1b[0m");
+			lines.push("");
+
+			const cats = [
+				...CATEGORY_ORDER.filter((c) => grouped[c]),
+				...Object.keys(grouped).filter((c) => !CATEGORY_ORDER.includes(c)),
+			];
+
+			for (const cat of cats) {
+				const mods = grouped[cat];
+				if (!mods || mods.length === 0) continue;
+				lines.push(`\x1b[33m${CATEGORY_LABELS[cat] ?? cat}\x1b[0m`);
+
+				// Two-column layout
+				const sorted = [...mods].sort((a, b) => a.name.localeCompare(b.name));
+				for (let i = 0; i < sorted.length; i += 2) {
+					const left = sorted[i]!;
+					const right = sorted[i + 1];
+					const leftStr = `  \x1b[36m${padRight(left.name, 14)}\x1b[0m ${left.description ?? ""}`;
+					const rightStr = right
+						? `  \x1b[36m${padRight(right.name, 14)}\x1b[0m ${right.description ?? ""}`
+						: "";
+					lines.push(rightStr ? `${leftStr.padEnd(44)}${rightStr}` : leftStr);
+				}
+				lines.push("");
+			}
+
+			lines.push("Type \x1b[1mhelp <command>\x1b[0m for usage details.");
+			return { stdout: lines.join("\n"), exitCode: 0 };
+		},
 	};
 }

package/src/commands/hostname.ts

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

package/src/commands/htop.ts

@@ -2,6 +2,8 @@ import type { ShellModule } from "../types/commands";
 
 export const htopCommand: ShellModule = {
 	name: "htop",
+	description: "System monitor",
+	category: "system",
 	params: [],
 	run: ({ mode }) => {
 		if (mode === "exec") {

package/src/commands/id.ts

@@ -0,0 +1,16 @@
+import type { ShellModule } from "../types/commands";
+
+export const idCommand: ShellModule = {
+	name: "id",
+	description: "Print user identity",
+	category: "system",
+	params: ["[user]"],
+	run: ({ authUser, shell, args }) => {
+		const target = args[0] ?? authUser;
+		const uid = target === "root" ? 0 : 1000;
+		const gid = uid;
+		const isSudo = shell.users.isSudoer(target);
+		const groups = isSudo ? `${gid}(${target}),0(root)` : `${gid}(${target})`;
+		return { stdout: `uid=${uid}(${target}) gid=${gid}(${target}) groups=${groups}`, exitCode: 0 };
+	},
+};

package/src/commands/index.ts

@@ -1,102 +1,118 @@
+/** biome-ignore-all lint/style/useNamingConvention: ENV VARIABLES */
 import type { VirtualShell } from "../VirtualShell";
 import type {
 	CommandContext,
 	CommandMode,
 	CommandResult,
+	ShellEnv,
 	ShellModule,
 } from "../types/commands";
 import { adduserCommand } from "./adduser";
+import { awkCommand } from "./awk";
+import { base64Command } from "./base64";
 import { catCommand } from "./cat";
 import { cdCommand } from "./cd";
+import { chmodCommand } from "./chmod";
 import { clearCommand } from "./clear";
+import { cpCommand } from "./cp";
 import { curlCommand } from "./curl";
+import { cutCommand } from "./cut";
+import { dateCommand } from "./date";
 import { deluserCommand } from "./deluser";
+import { dfCommand } from "./df";
+import { diffCommand } from "./diff";
+import { duCommand } from "./du";
 import { echoCommand } from "./echo";
 import { envCommand } from "./env";
 import { exitCommand } from "./exit";
 import { exportCommand } from "./export";
+import { findCommand } from "./find";
 import { grepCommand } from "./grep";
+import { groupsCommand } from "./groups";
+import { gunzipCommand, gzipCommand } from "./gzip";
+import { headCommand } from "./head";
 import { createHelpCommand } from "./help";
 import { hostnameCommand } from "./hostname";
 import { htopCommand } from "./htop";
+import { idCommand } from "./id";
+import { killCommand } from "./kill";
+import { lnCommand } from "./ln";
 import { lsCommand } from "./ls";
 import { mkdirCommand } from "./mkdir";
+import { mvCommand } from "./mv";
 import { nanoCommand } from "./nano";
 import { neofetchCommand } from "./neofetch";
 import { passwdCommand } from "./passwd";
+import { pingCommand } from "./ping";
+import { psCommand } from "./ps";
 import { pwdCommand } from "./pwd";
 import { rmCommand } from "./rm";
+import { sedCommand } from "./sed";
 import { setCommand } from "./set";
 import { shCommand } from "./sh";
+import { sleepCommand } from "./sleep";
+import { sortCommand } from "./sort";
 import { suCommand } from "./su";
 import { sudoCommand } from "./sudo";
+import { tailCommand } from "./tail";
+import { tarCommand } from "./tar";
+import { teeCommand } from "./tee";
 import { touchCommand } from "./touch";
+import { trCommand } from "./tr";
 import { treeCommand } from "./tree";
+import { unameCommand } from "./uname";
+import { uniqCommand } from "./uniq";
 import { unsetCommand } from "./unset";
+import { wcCommand } from "./wc";
 import { wgetCommand } from "./wget";
 import { whoCommand } from "./who";
 import { whoamiCommand } from "./whoami";
+import { xargsCommand } from "./xargs";
 
 const BASE_COMMANDS: ShellModule[] = [
-	pwdCommand,
-	whoamiCommand,
-	whoCommand,
-	hostnameCommand,
-	lsCommand,
-	cdCommand,
-	catCommand,
-	echoCommand,
-	mkdirCommand,
-	touchCommand,
-	rmCommand,
-	treeCommand,
-	nanoCommand,
+	// Navigation
+	pwdCommand, cdCommand, lsCommand, treeCommand,
+	// Files
+	catCommand, touchCommand, rmCommand, mkdirCommand, cpCommand, mvCommand, lnCommand,
+	chmodCommand, findCommand,
+	// Text processing
+	grepCommand, sedCommand, awkCommand, sortCommand, uniqCommand, wcCommand,
+	headCommand, tailCommand, cutCommand, trCommand, teeCommand, xargsCommand,
+	diffCommand,
+	// Archives
+	tarCommand, gzipCommand, gunzipCommand, base64Command,
+	// System info
+	whoamiCommand, whoCommand, hostnameCommand, idCommand, groupsCommand, unameCommand,
+	psCommand, killCommand, dfCommand, duCommand, dateCommand, sleepCommand, pingCommand,
+	// Shell
+	echoCommand, envCommand, exportCommand, setCommand, unsetCommand, shCommand,
+	clearCommand, exitCommand,
+	// Editors
+	nanoCommand, htopCommand,
+	// Network
+	curlCommand, wgetCommand,
+	// Users
+	adduserCommand, passwdCommand, deluserCommand, sudoCommand, suCommand,
+	// Misc
 	neofetchCommand,
-	htopCommand,
-	adduserCommand,
-	passwdCommand,
-	deluserCommand,
-	sudoCommand,
-	suCommand,
-	curlCommand,
-	envCommand,
-	wgetCommand,
-	grepCommand,
-	exportCommand,
-	setCommand,
-	unsetCommand,
-	shCommand,
-	clearCommand,
-	exitCommand,
 ];
 
 const customCommands: ShellModule[] = [];
-
-const helpCommand = createHelpCommand(() =>
-	getCommandModules().map((cmd) => cmd.name),
-);
-
 const commandRegistry = new Map<string, ShellModule>();
 let cachedCommandNames: string[] | null = null;
 
+const helpCommand = createHelpCommand(() => getCommandModules().map((cmd) => cmd.name));
+
 function buildCache(): void {
+	commandRegistry.clear();
 	for (const mod of getCommandModules()) {
 		commandRegistry.set(mod.name, mod);
-		for (const alias of mod.aliases ?? []) {
-			commandRegistry.set(alias, mod);
-		}
+		for (const alias of mod.aliases ?? []) commandRegistry.set(alias, mod);
 	}
 	cachedCommandNames = Array.from(commandRegistry.keys()).sort();
 }
 
 function getCommandModules(): ShellModule[] {
-	// console.log("Loading command modules...");
-	// console.log(
-	// 	`Base commands: ${BASE_COMMANDS.map((cmd) => cmd.name).join(", ")}`,
-	// );
-	// console.log(
-	// 	`Custom commands: ${customCommands.map((cmd) => cmd.name).join(", ")}`,
-	// );
 	return [...BASE_COMMANDS, ...customCommands, helpCommand];
 }
 
@@ -104,23 +120,13 @@ export function registerCommand(module: ShellModule): void {
 	const normalized: ShellModule = {
 		...module,
 		name: module.name.trim().toLowerCase(),
-		aliases: module.aliases?.map((alias) => alias.trim().toLowerCase()),
+		aliases: module.aliases?.map((a) => a.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",
-		);
-	}
-
-	for (const name of names) {
-		if (commandRegistry.has(name)) {
-			throw new Error(`Command '${name}' already exists`);
-		}
-		commandRegistry.set(name, normalized);
+	if (names.some((n) => n.length === 0 || /\s/.test(n))) {
+		throw new Error("Command names must be non-empty and contain no spaces");
 	}
-
+	customCommands.push(normalized);
 	buildCache();
 }
 
@@ -129,24 +135,20 @@ export function createCustomCommand(
 	params: string[],
 	run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>,
 ): ShellModule {
-	return {
-		name,
-		params,
-		run,
-	};
+	return { name, params, run };
 }
 
 export function getCommandNames(): string[] {
-	if (!cachedCommandNames) {
-		buildCache();
-	}
+	if (!cachedCommandNames) buildCache();
 	return cachedCommandNames!;
 }
 
+export function getCommandModulesPublic(): ShellModule[] {
+	return getCommandModules();
+}
+
 export function resolveModule(name: string): ShellModule | undefined {
-	if (!cachedCommandNames) {
-		buildCache();
-	}
+	if (!cachedCommandNames) buildCache();
 	return commandRegistry.get(name.toLowerCase());
 }
 
@@ -156,52 +158,44 @@ function splitArgsRespectingQuotes(input: string): string[] {
 	let inQuotes = false;
 	let quoteChar = "";
 
-	for (let i = 0; i < input.length; i += 1) {
+	for (let i = 0; i < input.length; i++) {
 		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 (!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 = "";
-			}
+			if (current.length > 0) { tokens.push(current); current = ""; }
 			continue;
 		}
-
 		current += ch;
 	}
-
-	if (current.length > 0) {
-		tokens.push(current);
-	}
-
+	if (current.length > 0) tokens.push(current);
 	return tokens;
 }
 
 function parseInput(rawInput: string): { commandName: string; args: string[] } {
 	const parts = splitArgsRespectingQuotes(rawInput.trim());
+	return { commandName: parts[0]?.toLowerCase() ?? "", args: parts.slice(1) };
+}
+
+export function makeDefaultEnv(authUser: string, hostname: string): ShellEnv {
 	return {
-		commandName: parts[0]?.toLowerCase() ?? "",
-		args: parts.slice(1),
+		vars: {
+			PATH: "/usr/local/bin:/usr/bin:/bin",
+			HOME: `/home/${authUser}`,
+			USER: authUser,
+			LOGNAME: authUser,
+			SHELL: "/bin/sh",
+			TERM: "xterm-256color",
+			HOSTNAME: hostname,
+			PS1: "\\u@\\h:\\w\\$ ",
+		},
+		lastExitCode: 0,
 	};
 }
 
-// Internal async function for pipeline execution
-
 export async function runCommand(
 	rawInput: string,
 	authUser: string,
@@ -210,50 +204,37 @@ export async function runCommand(
 	cwd: string,
 	shell: VirtualShell,
 	stdin?: string,
+	env?: ShellEnv,
 ): Promise<CommandResult> {
 	const trimmed = rawInput.trim();
-
-	if (trimmed.length === 0) {
-		return { exitCode: 0 };
-	}
-
-	if (trimmed.includes("|") || trimmed.includes(">") || trimmed.includes("<")) {
-		const { parseShellPipeline } = await import("../VirtualShell/shellParser");
-		const { executePipeline } = await import("../SSHMimic/executor");
-
-		const pipeline = parseShellPipeline(trimmed);
-		if (!pipeline.isValid) {
-			return {
-				stderr: pipeline.error || "Syntax error",
-				exitCode: 1,
-			};
-		}
-
+	if (trimmed.length === 0) return { exitCode: 0 };
+
+	const shellEnv: ShellEnv = env ?? makeDefaultEnv(authUser, hostname);
+
+	// Detect shell operators
+	if (
+		/(?<![|&])[|](?![|])/.test(trimmed) ||
+		trimmed.includes(">") ||
+		trimmed.includes("<") ||
+		trimmed.includes("&&") ||
+		trimmed.includes("||") ||
+		trimmed.includes(";")
+	) {
+		const { parseScript } = await import("../VirtualShell/shellParser");
+		const { executeStatements } = await import("../SSHMimic/executor");
+		const script = parseScript(trimmed);
+		if (!script.isValid) return { stderr: script.error || "Syntax error", exitCode: 1 };
 		try {
-			return await executePipeline(
-				pipeline,
-				authUser,
-				hostname,
-				mode,
-				cwd,
-				shell,
-			);
+			return await executeStatements(script.statements, authUser, hostname, mode, cwd, shell, shellEnv);
 		} catch (error: unknown) {
-			const message =
-				error instanceof Error ? error.message : "Pipeline execution failed";
-			return { stderr: message, exitCode: 1 };
+			return { stderr: error instanceof Error ? error.message : "Execution failed", exitCode: 1 };
 		}
 	}
 
 	const { commandName, args } = parseInput(trimmed);
 	const mod = resolveModule(commandName);
 
-	if (!mod) {
-		return {
-			stderr: `Command '${trimmed}' not found`,
-			exitCode: 127,
-		};
-	}
+	if (!mod) return { stderr: `${commandName}: command not found`, exitCode: 127 };
 
 	try {
 		return await mod.run({
@@ -266,9 +247,9 @@ export async function runCommand(
 			stdin,
 			cwd,
 			shell,
+			env: shellEnv,
 		});
 	} catch (error: unknown) {
-		const message = error instanceof Error ? error.message : "Command failed";
-		return { stderr: message, exitCode: 1 };
+		return { stderr: error instanceof Error ? error.message : "Command failed", exitCode: 1 };
 	}
 }

package/src/commands/kill.ts

@@ -0,0 +1,14 @@
+import type { ShellModule } from "../types/commands";
+
+export const killCommand: ShellModule = {
+	name: "kill",
+	description: "Send signal to process",
+	category: "system",
+	params: ["[-9] <pid>"],
+	run: ({ args }) => {
+		const pid = args.find((a) => !a.startsWith("-"));
+		if (!pid) return { stderr: "kill: no pid specified", exitCode: 1 };
+		// In virtual env, we just acknowledge the kill
+		return { stdout: ``, exitCode: 0 };
+	},
+};

package/src/commands/ln.ts

@@ -0,0 +1,49 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const lnCommand: ShellModule = {
+	name: "ln",
+	description: "Create links",
+	category: "files",
+	params: ["[-s] <target> <link_name>"],
+	run: ({ authUser, shell, cwd, args }) => {
+		const symbolic = ifFlag(args, ["-s", "--symbolic"]);
+		const positionals = args.filter((a) => !a.startsWith("-"));
+		const [targetArg, linkArg] = positionals;
+
+		if (!targetArg || !linkArg) {
+			return { stderr: "ln: missing operand", exitCode: 1 };
+		}
+
+		const linkPath = resolvePath(cwd, linkArg);
+		const targetPath = symbolic
+			? targetArg // keep relative for symlinks
+			: resolvePath(cwd, targetArg);
+
+		try {
+			assertPathAccess(authUser, linkPath, "ln");
+
+			if (!symbolic) {
+				// Hard link — copy file contents
+				const srcPath = resolvePath(cwd, targetArg);
+				assertPathAccess(authUser, srcPath, "ln");
+				if (!shell.vfs.exists(srcPath)) {
+					return {
+						stderr: `ln: ${targetArg}: No such file or directory`,
+						exitCode: 1,
+					};
+				}
+				const content = shell.vfs.readFile(srcPath);
+				shell.writeFileAsUser(authUser, linkPath, content);
+			} else {
+				shell.vfs.symlink(targetPath, linkPath);
+			}
+
+			return { exitCode: 0 };
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return { stderr: `ln: ${msg}`, exitCode: 1 };
+		}
+	},
+};

package/src/commands/ls.ts

@@ -28,6 +28,8 @@ function formatDate(date: Date): string {
 
 export const lsCommand: ShellModule = {
 	name: "ls",
+	description: "List directory contents",
+	category: "navigation",
 	params: ["[path]"],
 	run: ({ authUser, shell, cwd, args }) => {
 		const longFormat = ifFlag(args, ["-l", "--long"]);

package/src/commands/mkdir.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const mkdirCommand: ShellModule = {
 	name: "mkdir",
+	description: "Make directories",
+	category: "files",
 	params: ["<dir>"],
 	run: ({ authUser, shell, cwd, args }) => {
 		if (args.length === 0) {

package/src/commands/mv.ts

@@ -0,0 +1,45 @@
+import type { ShellModule } from "../types/commands";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const mvCommand: ShellModule = {
+	name: "mv",
+	description: "Move or rename files",
+	category: "files",
+	params: ["<source> <dest>"],
+	run: ({ authUser, shell, cwd, args }) => {
+		const positionals = args.filter((a) => !a.startsWith("-"));
+		const [srcArg, destArg] = positionals;
+
+		if (!srcArg || !destArg) {
+			return { stderr: "mv: missing operand", exitCode: 1 };
+		}
+
+		const srcPath = resolvePath(cwd, srcArg);
+		const destPath = resolvePath(cwd, destArg);
+
+		try {
+			assertPathAccess(authUser, srcPath, "mv");
+			assertPathAccess(authUser, destPath, "mv");
+
+			if (!shell.vfs.exists(srcPath)) {
+				return {
+					stderr: `mv: ${srcArg}: No such file or directory`,
+					exitCode: 1,
+				};
+			}
+
+			// If dest is a directory, move into it
+			const finalDest =
+				shell.vfs.exists(destPath) &&
+				shell.vfs.stat(destPath).type === "directory"
+					? `${destPath}/${srcArg.split("/").pop()}`
+					: destPath;
+
+			shell.vfs.move(srcPath, finalDest);
+			return { exitCode: 0 };
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return { stderr: `mv: ${msg}`, exitCode: 1 };
+		}
+	},
+};

package/src/commands/nano.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const nanoCommand: ShellModule = {
 	name: "nano",
+	description: "Text editor",
+	category: "shell",
 	params: ["<file>"],
 	run: ({ authUser, shell, cwd, args }) => {
 		const fileArg = args[0];

package/src/commands/neofetch.ts

@@ -5,6 +5,8 @@ import { getAllEnvVars } from "./set";
 
 export const neofetchCommand: ShellModule = {
 	name: "neofetch",
+	description: "System info display",
+	category: "misc",
 	params: ["[--off]"],
 	run: ({ args, authUser, hostname, shell }) => {
 		const env = getAllEnvVars(authUser);

package/src/commands/passwd.ts

@@ -2,6 +2,8 @@ import type { ShellModule } from "../types/commands";
 
 export const passwdCommand: ShellModule = {
 	name: "passwd",
+	description: "Change user password",
+	category: "users",
 	params: ["<username> <password>"],
 	run: async ({ authUser, args, shell }) => {
 		const [username, password] = args;