typescript-virtual-container 1.3.4 → 1.4.1

package/src/commands/unset.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Remove shell variable from the environment.
+ * @category shell
+ * @params ["<VAR>"]
+ */
 export const unsetCommand: ShellModule = {
 	name: "unset",
 	description: "Remove shell variable",

package/src/commands/uptime.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Tell how long the system has been running.
+ * @category system
+ * @params ["[-p] [-s]"]
+ */
 export const uptimeCommand: ShellModule = {
 	name: "uptime",
 	description: "Tell how long the system has been running",

package/src/commands/wc.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Count words, lines, and/or bytes in files or stdin.
+ * @category text
+ * @params ["[-l] [-w] [-c] [file...]"]
+ */
 export const wcCommand: ShellModule = {
 	name: "wc",
 	description: "Count words/lines/bytes",

package/src/commands/wget.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag, parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath, stripUrlFilename } from "./helpers";
 
+/**
+ * Download files from the web (fetch-based implementation).
+ * @category network
+ * @params ["[options] <url>"]
+ */
 export const wgetCommand: ShellModule = {
 	name: "wget",
 	description: "File downloader (pure fetch)",
@@ -44,7 +49,18 @@ export const wgetCommand: ShellModule = {
 			};
 		}
 
-		const url = positionals[0];
+		const urlWithoutProtocol = positionals[0];
+		if (!urlWithoutProtocol) {
+			return {
+				stderr: "wget: missing URL\nUsage: wget [OPTION]... [URL]...",
+				exitCode: 1,
+			};
+		}
+
+		const url = urlWithoutProtocol.startsWith("http://") ||
+			urlWithoutProtocol.startsWith("https://")
+			? urlWithoutProtocol
+			: `http://${urlWithoutProtocol}`;
 		if (!url)
 			return {
 				stderr: "wget: missing URL\nUsage: wget [OPTION]... [URL]...",

package/src/commands/who.ts

@@ -1,6 +1,11 @@
 import { formatLoginDate } from "../SSHMimic/loginFormat";
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Show active user sessions.
+ * @category system
+ * @params []
+ */
 export const whoCommand: ShellModule = {
 	name: "who",
 	description: "Show active sessions",

package/src/commands/whoami.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Print the current user name.
+ * @category system
+ * @params []
+ */
 export const whoamiCommand: ShellModule = {
 	name: "whoami",
 	description: "Print current user",

package/src/commands/xargs.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { runCommand } from "./runtime";
 
+/**
+ * Build and execute commands from stdin arguments.
+ * @category text
+ * @params ["[command] [args...]"]
+ */
 export const xargsCommand: ShellModule = {
 	name: "xargs",
 	description: "Build and execute command lines from stdin",

package/src/self-standalone.ts

@@ -1,10 +1,13 @@
+import { readFile, unlink, writeFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { stdin, stdout } from "node:process";
 import { createInterface, type Interface } from "node:readline";
 
 import { makeDefaultEnv, runCommand } from "./commands/runtime";
+import { spawnNanoEditorProcess } from "./modules/shellInteractive";
 import { buildLoginBanner, type LoginBannerState } from "./SSHMimic/loginBanner";
 import { buildPrompt } from "./SSHMimic/prompt";
+import type { CommandResult, PasswordChallenge, SudoChallenge } from "./types/commands";
 import { VirtualShell } from "./VirtualShell";
 
 const hostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
@@ -47,9 +50,55 @@ function readLastLogin(username: string): LoginBannerState | null {
 	}
 }
 
-function askQuestion(rl: Interface, promptText: string): Promise<string> {
+function askHiddenQuestion(rl: Interface, promptText: string): Promise<string> {
 	return new Promise((resolve) => {
-		rl.question(promptText, resolve);
+		if (!stdin.isTTY || !stdout.isTTY) {
+			rl.question(promptText, resolve);
+			return;
+		}
+
+		const wasRawMode = Boolean(stdin.isRaw);
+		let buffer = "";
+
+		const cleanup = (): void => {
+			stdin.off("data", onData);
+			if (!wasRawMode) {
+				stdin.setRawMode(false);
+			}
+			rl.resume();
+		};
+
+		const finish = (value: string): void => {
+			cleanup();
+			stdout.write("\n");
+			resolve(value);
+		};
+
+		const onData = (chunk: Buffer): void => {
+			const input = chunk.toString("utf8");
+			for (let index = 0; index < input.length; index += 1) {
+				const ch = input[index]!;
+				if (ch === "\r" || ch === "\n") {
+					finish(buffer);
+					return;
+				}
+				if (ch === "\u007f" || ch === "\b") {
+					buffer = buffer.slice(0, -1);
+					continue;
+				}
+				if (ch >= " ") {
+					buffer += ch;
+				}
+			}
+		};
+
+		rl.pause();
+		stdout.write(promptText);
+		if (!wasRawMode) {
+			stdin.setRawMode(true);
+		}
+		stdin.resume();
+		stdin.on("data", onData);
 	});
 }
 
@@ -65,6 +114,53 @@ function writeLastLogin(username: string, from: string): void {
 	);
 }
 
+async function flushVfs(): Promise<void> {
+	await virtualShell.vfs.flushMirror();
+}
+
+function loadHistory(): string[] {
+	const historyPath = "/virtual-env-js/.bash_history";
+	if (!virtualShell.vfs.exists(historyPath)) {
+		virtualShell.vfs.writeFile(historyPath, "");
+		return [];
+	}
+
+	return virtualShell.vfs
+		.readFile(historyPath)
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+}
+
+function saveHistory(history: string[]): void {
+	const data = history.length > 0 ? `${history.join("\n")}\n` : "";
+	virtualShell.vfs.writeFile("/virtual-env-js/.bash_history", data);
+}
+
+function applySessionState(
+	authUserState: string,
+	cwdState: string,
+	result: CommandResult,
+	shellEnvState: ReturnType<typeof makeDefaultEnv>,
+): { authUser: string; cwd: string } {
+	let authUser = authUserState;
+	let cwd = cwdState;
+
+	if (result.switchUser) {
+		authUser = result.switchUser;
+		cwd = result.nextCwd ?? `/home/${authUser}`;
+		shellEnvState.vars.USER = authUser;
+		shellEnvState.vars.LOGNAME = authUser;
+		shellEnvState.vars.HOME = `/home/${authUser}`;
+		shellEnvState.vars.PWD = cwd;
+	} else if (result.nextCwd) {
+		cwd = result.nextCwd;
+		shellEnvState.vars.PWD = cwd;
+	}
+
+	return { authUser, cwd };
+}
+
 virtualShell.addCommand("demo", [], () => {
 	return {
 		stdout: "This is a demo command. It does nothing useful.",
@@ -75,6 +171,9 @@ virtualShell.addCommand("demo", [], () => {
 async function runReadlineShell() {
 	const rl = createInterface({ input: stdin, output: stdout, terminal: true });
 	await virtualShell.ensureInitialized();
+	let history = loadHistory();
+	const rlWithHistory = rl as Interface & { history: string[] };
+	rlWithHistory.history = [...history].reverse();
 
 	const selectedUser = initialUser.trim() || "root";
 	const userExists = virtualShell.users.getPasswordHash(selectedUser) !== null;
@@ -88,9 +187,207 @@ async function runReadlineShell() {
 	let cwd = `/home/${authUser}`;
 	shellEnv.vars.PWD = cwd;
 	const remoteAddress = "localhost";
+	const terminalSize = {
+		cols: stdout.columns ?? 80,
+		rows: stdout.rows ?? 24,
+	};
+
+	async function startNanoEditor(
+		targetPath: string,
+		initialContent: string,
+		tempPath: string,
+	): Promise<void> {
+		if (virtualShell.vfs.exists(targetPath)) {
+			await writeFile(tempPath, initialContent, "utf8");
+		}
+
+		rl.pause();
+		const editor = spawnNanoEditorProcess(
+			tempPath,
+			terminalSize,
+			{
+				write: stdout.write.bind(stdout),
+				exit: () => undefined,
+				end: () => undefined,
+			} as unknown as Parameters<typeof spawnNanoEditorProcess>[2],
+		);
+
+		const wasRawMode = Boolean(stdin.isRaw);
+		const forwardInput = (chunk: Buffer): void => {
+			editor.stdin.write(chunk);
+		};
+
+		stdin.resume();
+		if (!wasRawMode) {
+			stdin.setRawMode(true);
+		}
+		stdin.on("data", forwardInput);
+
+		await new Promise<void>((resolve) => {
+			const cleanup = (): void => {
+				stdin.off("data", forwardInput);
+				if (!wasRawMode) {
+					stdin.setRawMode(false);
+				}
+				rl.resume();
+			};
+
+			editor.on("error", (error: Error) => {
+				cleanup();
+				stdout.write(`nano: ${error.message}\r\n`);
+				resolve();
+			});
+
+			editor.on("close", async () => {
+				cleanup();
+				rl.write("", { ctrl: true, name: "u" });
+				try {
+					const updatedContent = await readFile(tempPath, "utf8");
+					virtualShell.writeFileAsUser(authUser, targetPath, updatedContent);
+					await flushVfs();
+				} catch {
+					// Save skipped or temp file missing.
+				}
+
+				await unlink(tempPath).catch(() => undefined);
+				stdout.write("\r\n");
+				resolve();
+			});
+		});
+	}
+
+	async function handleSudoChallenge(challenge: SudoChallenge): Promise<void> {
+		if (challenge.onPassword) {
+			let promptText = challenge.prompt;
+			while (true) {
+				const typed = await askHiddenQuestion(rl, promptText);
+				const step = await challenge.onPassword(typed, virtualShell);
+				if (step.result === null) {
+					promptText = step.nextPrompt ?? promptText;
+					continue;
+				}
+
+				await handleCommandResult(step.result);
+				return;
+			}
+		}
+
+		const password = await askHiddenQuestion(rl, challenge.prompt);
+		if (!virtualShell.users.verifyPassword(challenge.username, password)) {
+			process.stderr.write("Sorry, try again.\n");
+			return;
+		}
+
+		if (!challenge.commandLine) {
+			authUser = challenge.targetUser;
+			cwd = `/home/${authUser}`;
+			shellEnv.vars.USER = authUser;
+			shellEnv.vars.LOGNAME = authUser;
+			shellEnv.vars.HOME = `/home/${authUser}`;
+			shellEnv.vars.PWD = cwd;
+			return;
+		}
+
+		const runCwd = challenge.loginShell ? `/home/${challenge.targetUser}` : cwd;
+		const nestedResult = await runCommand(
+			challenge.commandLine,
+			challenge.targetUser,
+			hostname,
+			"shell",
+			runCwd,
+			virtualShell,
+			undefined,
+			shellEnv,
+		);
+		await handleCommandResult(nestedResult);
+	}
+
+	async function handlePasswordChallenge(
+		challenge: PasswordChallenge,
+	): Promise<void> {
+		const first = await askHiddenQuestion(rl, challenge.prompt);
+		if (challenge.confirmPrompt) {
+			const second = await askHiddenQuestion(rl, challenge.confirmPrompt);
+			if (second !== first) {
+				process.stderr.write("passwords do not match\n");
+				return;
+			}
+		}
+
+		switch (challenge.action) {
+			case "passwd":
+				await virtualShell.users.setPassword(challenge.targetUsername, first);
+				stdout.write("passwd: password updated successfully\n");
+				break;
+			case "adduser":
+				if (!challenge.newUsername) {
+					process.stderr.write("adduser: missing username\n");
+					return;
+				}
+				await virtualShell.users.addUser(challenge.newUsername, first);
+				stdout.write(`adduser: user '${challenge.newUsername}' created\n`);
+				break;
+			case "deluser":
+				await virtualShell.users.deleteUser(challenge.targetUsername);
+				stdout.write(`Removing user '${challenge.targetUsername}' ...\ndeluser: done.\n`);
+				break;
+			case "su":
+				authUser = challenge.targetUsername;
+				cwd = `/home/${authUser}`;
+				shellEnv.vars.USER = authUser;
+				shellEnv.vars.LOGNAME = authUser;
+				shellEnv.vars.HOME = `/home/${authUser}`;
+				shellEnv.vars.PWD = cwd;
+				break;
+		}
+	}
+
+	async function handleCommandResult(result: CommandResult): Promise<void> {
+		if (result.openEditor) {
+			await startNanoEditor(
+				result.openEditor.targetPath,
+				result.openEditor.initialContent,
+				result.openEditor.tempPath,
+			);
+			return;
+		}
+
+		if (result.sudoChallenge) {
+			await handleSudoChallenge(result.sudoChallenge);
+			return;
+		}
+
+		if (result.passwordChallenge) {
+			await handlePasswordChallenge(result.passwordChallenge);
+			return;
+		}
+
+		if (result.stdout) {
+			stdout.write(result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
+		}
+
+		if (result.stderr) {
+			process.stderr.write(result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`);
+		}
+
+		if (result.clearScreen) {
+			stdout.write("\u001b[2J\u001b[H");
+			console.clear();
+		}
+
+		const updatedState = applySessionState(authUser, cwd, result, shellEnv);
+		authUser = updatedState.authUser;
+		cwd = updatedState.cwd;
+
+		if (result.closeSession) {
+			await flushVfs();
+			rl.close();
+			process.exit(result.exitCode ?? 0);
+		}
+	}
 
 	if (process.env.USER !== "root" && virtualShell.users.hasPassword(authUser)) {
-		const password = await askQuestion(rl, `Password for ${authUser}: `);
+		const password = await askHiddenQuestion(rl, `Password for ${authUser}: `);
 		if (!virtualShell.users.verifyPassword(authUser, password)) {
 			process.stderr.write("self-standalone: authentication failed\n");
 			process.exit(1);
@@ -114,12 +411,16 @@ async function runReadlineShell() {
 	});
 
 	rl.on("close", () => {
-		console.log("")
-		process.exit(0);
+		void (async () => {
+			await flushVfs();
+			console.log("");
+			process.exit(0);
+		})();
 	});
 
 	stdout.write(buildLoginBanner(hostname, virtualShell.properties, readLastLogin(authUser)));
 	writeLastLogin(authUser, remoteAddress);
+	await flushVfs();
 	prompt();
 
 	while (true) {
@@ -128,37 +429,19 @@ async function runReadlineShell() {
 		});
 
 		rl.pause();
-
-		const result = await runCommand(inputLine, authUser, hostname, "shell", cwd, virtualShell, undefined, shellEnv);
-
-		if (result.stdout) {
-			stdout.write(result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
-		}
-
-		if (result.stderr) {
-			process.stderr.write(result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`);
-		}
-
-		if (result.clearScreen) {
-			stdout.write("\u001b[2J\u001b[H");
+		if (inputLine.trim().length > 0) {
+			history.push(inputLine);
+			if (history.length > 500) {
+				history = history.slice(history.length - 500);
+			}
+			saveHistory(history);
+			rlWithHistory.history = [...history].reverse();
 		}
 
-		if (result.switchUser) {
-			authUser = result.switchUser;
-			cwd = result.nextCwd ?? `/home/${authUser}`;
-			shellEnv.vars.USER = authUser;
-			shellEnv.vars.LOGNAME = authUser;
-			shellEnv.vars.HOME = `/home/${authUser}`;
-			shellEnv.vars.PWD = cwd;
-		} else if (result.nextCwd) {
-			cwd = result.nextCwd;
-			shellEnv.vars.PWD = cwd;
-		}
+		const result = await runCommand(inputLine, authUser, hostname, "shell", cwd, virtualShell, undefined, shellEnv);
+		await handleCommandResult(result);
 
-		if (result.closeSession) {
-			rl.close();
-			process.exit(result.exitCode ?? 0);
-		}
+		await flushVfs();
 
 		prompt();
 		rl.resume();

package/src/types/commands.ts

@@ -31,6 +31,8 @@ export interface CommandResult {
 	openHtop?: boolean;
 	/** Request sudo password challenge flow. */
 	sudoChallenge?: SudoChallenge;
+	/** Request a generic password challenge (adduser, passwd). */
+	passwordChallenge?: PasswordChallenge;
 }
 
 /** Deferred sudo challenge metadata returned by sudo command. */
@@ -45,6 +47,41 @@ export interface SudoChallenge {
 	loginShell: boolean;
 	/** Prompt text shown before password input. */
 	prompt: string;
+	/**
+	 * Challenge mode.
+	 * - `"sudo"` (default): verify `username`'s password, then run `commandLine`.
+	 * - `"passwd"`: multi-step new-password flow; `onPassword` handles each step.
+	 * - `"confirm"`: text confirmation flow (e.g. deluser); `onPassword` receives typed text.
+	 */
+	mode?: "sudo" | "passwd" | "confirm";
+	/**
+	 * Optional async handler called when the user submits input.
+	 * Receives the typed text and the shell instance.
+	 * Returns a `CommandResult` written to the terminal, or `null` to show
+	 * another prompt (pass `nextPrompt` to change the prompt text).
+	 */
+	onPassword?: (input: string, shell: import("../VirtualShell").VirtualShell) => Promise<{
+		result: CommandResult | null;
+		nextPrompt?: string;
+	}>;
+}
+
+/** Generic password challenge — used by adduser, passwd, deluser. */
+export interface PasswordChallenge {
+	/** Lines to print before the first prompt. */
+	preamble?: string;
+	/** Primary prompt text (e.g. "New password: "). */
+	prompt: string;
+	/** If set, a second prompt is shown for confirmation. */
+	confirmPrompt?: string;
+	/** Prompt shown for a destructive confirmation (y/N). */
+	confirmText?: string;
+	/** Tag identifying what to do with the entered value. */
+	action: "adduser" | "passwd" | "deluser" | "su";
+	/** Username targeted by the action. */
+	targetUsername: string;
+	/** For adduser: the new user's username (already validated). */
+	newUsername?: string;
 }
 
 /** State payload used by nano command interactive editor flow. */

package/src/utils/tokenize.ts

@@ -0,0 +1,78 @@
+/**
+ * tokenize.ts
+ *
+ * Shared shell tokenizer used by `shellParser.ts` and `runtime.ts`.
+ * Splits a shell input string into tokens respecting single and double
+ * quotes, and separates `>`, `>>`, `<` as standalone redirect tokens.
+ */
+
+/**
+ * Tokenize a shell command line respecting quoted strings and redirect
+ * operators.
+ *
+ * - Single-quoted content is preserved verbatim.
+ * - Double-quoted content is preserved (expansion happens later).
+ * - `>`, `>>`, and `<` are emitted as standalone tokens.
+ *
+ * @param input Raw shell command string.
+ * @returns Array of string tokens.
+ */
+export function tokenizeCommand(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQ = false;
+	let qChar = "";
+	let i = 0;
+
+	while (i < input.length) {
+		const ch = input[i]!;
+		const next = input[i + 1];
+
+		if ((ch === '"' || ch === "'") && !inQ) {
+			inQ = true;
+			qChar = ch;
+			i++;
+			continue;
+		}
+		if (inQ && ch === qChar) {
+			inQ = false;
+			qChar = "";
+			i++;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			i++;
+			continue;
+		}
+
+		if (ch === " ") {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			i++;
+			continue;
+		}
+
+		if ((ch === ">" || ch === "<") && !inQ) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			if (ch === ">" && next === ">") {
+				tokens.push(">>");
+				i += 2;
+			} else {
+				tokens.push(ch);
+				i++;
+			}
+			continue;
+		}
+
+		current += ch;
+		i++;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}

package/tests/new-features.test.ts

@@ -223,7 +223,7 @@ describe("Package manager (apt/dpkg)", () => {
 	});
 
 	test("neofetch shows package count after installs", async () => {
-		await client.exec("apt install curl wget htop");
+		await client.exec("apt install curl wget htop neofetch");
 		const r = await client.exec("neofetch");
 		expect(r.exitCode).toBe(0);
 		expect(r.stdout).toContain("(dpkg)");
@@ -675,7 +675,7 @@ describe("/proc/self and /proc/<pid>", () => {
 	});
 });
 
-import { diffSnapshots, formatDiff, assertDiff } from "../src";
+import { assertDiff, diffSnapshots, formatDiff } from "../src";
 
 describe("VFS snapshot diff tooling", () => {
 	let shell5: VirtualShell;