typescript-virtual-container 1.3.4 → 1.4.0

package/src/commands/shift.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Shift positional parameters (remove first N arguments).
+ * @category shell
+ * @params ["[n]"]
+ */
 export const shiftCommand: ShellModule = {
 	name: "shift",
 	description: "Shift positional parameters",
@@ -22,6 +27,11 @@ export const shiftCommand: ShellModule = {
 	},
 };
 
+/**
+ * Trap signals and execute actions on signal receipt or shell exit.
+ * @category shell
+ * @params ["[action] [signal...]"]
+ */
 export const trapCommand: ShellModule = {
 	name: "trap",
 	description: "Trap signals and events",

package/src/commands/sleep.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Delay execution for a specified number of seconds.
+ * @category system
+ * @params ["<seconds>"]
+ */
 export const sleepCommand: ShellModule = {
 	name: "sleep",
 	description: "Delay execution",

package/src/commands/sort.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Sort lines of text with various options (reverse, numeric, unique).
+ * @category text
+ * @params ["[-r] [-n] [-u] [-k <col>] [file...]"]
+ */
 export const sortCommand: ShellModule = {
 	name: "sort",
 	description: "Sort lines of text",

package/src/commands/source.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { resolvePath } from "./helpers";
 import { runCommand } from "./runtime";
 
+/**
+ * Execute commands from a file in the current shell environment.
+ * @category shell
+ * @params ["<file> [args...]"]
+ */
 export const sourceCommand: ShellModule = {
 	name: "source",
 	aliases: ["."],

package/src/commands/stat.ts

@@ -0,0 +1,61 @@
+import type { ShellModule } from "../types/commands";
+import { resolvePath } from "./helpers";
+
+/**
+ * Display file or filesystem status.
+ * Outputs: path, size, mode, type, timestamps — similar to `stat` on Linux.
+ */
+export const statCommand: ShellModule = {
+	name: "stat",
+	description: "Display file status",
+	category: "files",
+	params: ["[-c <format>] <file>"],
+	run: ({ shell, cwd, args }) => {
+		const fmtIdx = args.findIndex((a) => a === "-c" || a === "--format");
+		const fmt = fmtIdx !== -1 ? args[fmtIdx + 1] : undefined;
+		const file = args.find((a) => !a.startsWith("-") && a !== fmt);
+		if (!file) return { stderr: "stat: missing operand\n", exitCode: 1 };
+
+		const p = resolvePath(cwd, file);
+		if (!shell.vfs.exists(p)) {
+			return { stderr: `stat: cannot stat '${file}': No such file or directory\n`, exitCode: 1 };
+		}
+
+		const st = shell.vfs.stat(p);
+		const isDir = st.type === "directory";
+		const _isLink = shell.vfs.isSymlink(p);
+		const isSymlink = shell.vfs.isSymlink(p);
+		const modePerm = (mode: number): string => {
+			const bits = [0o400,0o200,0o100,0o040,0o020,0o010,0o004,0o002,0o001];
+			const syms = ["r","w","x","r","w","x","r","w","x"];
+			return (isDir ? "d" : isSymlink ? "l" : "-") +
+				bits.map((b, i) => mode & b ? syms[i] : "-").join("");
+		};
+		const octal = (st.mode).toString(8).padStart(4, "0");
+		const modeStr = modePerm(st.mode);
+		const size = "size" in st ? (st as {size: number}).size : 0;
+		const ts = (d: Date) => d.toISOString().replace("T", " ").replace(/\.\d+Z$/, " +0000");
+
+		// -c format string support
+		if (fmt) {
+			const out = fmt
+				.replace("%n", file)
+				.replace("%s", String(size))
+				.replace("%a", octal.slice(1)) // access in octal (no leading 0)
+				.replace("%A", modeStr)
+				.replace("%F", isSymlink ? "symbolic link" : isDir ? "directory" : "regular file")
+				.replace("%y", ts(st.updatedAt))
+				.replace("%z", ts(st.updatedAt));
+			return { stdout: `${out}\n`, exitCode: 0 };
+		}
+
+		const out = [
+			`  File: ${file}${isSymlink ? ` -> ${shell.vfs.resolveSymlink(p)}` : ""}`,
+			`  Size: ${size}${"\t".repeat(3)}${isSymlink ? "symbolic link" : isDir ? "directory" : "regular file"}`,
+			`Access: (${octal}/${modeStr})  Uid: (    0/    root)   Gid: (    0/    root)`,
+			`Modify: ${ts(st.updatedAt)}`,
+			`Change: ${ts(st.updatedAt)}`,
+		].join("\n");
+		return { stdout: `${out}\n`, exitCode: 0 };
+	},
+};

package/src/commands/su.ts

@@ -1,33 +1,71 @@
 import type { ShellModule } from "../types/commands";
-import { getArg } from "./command-helpers";
+import { runCommand } from "./runtime";
 
+/**
+ * Switch to another user account.
+ *
+ * Usage:
+ *   su [username]        — switch to username (defaults to root)
+ *   su - [username]      — login shell (changes cwd to target home)
+ *   su -c 'cmd' [user]   — run command as user
+ *
+ * - Root can switch to any user without a password.
+ * - Non-root sudoers must enter the target user's password.
+ * - Non-sudoers are denied.
+ * - Switching to a non-existent user returns an error immediately.
+ */
 export const suCommand: ShellModule = {
 	name: "su",
 	description: "Switch user",
 	category: "users",
-	params: ["- <username>"],
-	run: ({ authUser, shell, args }) => {
-		const users = shell.users!;
-		const targetUser = getArg(args, 0, { flags: ["-"] });
+	params: ["[-] [-c <cmd>] [username]"],
+	run: async ({ authUser, shell, args, hostname, mode, cwd }) => {
+		const loginShellFlag = args.includes("-") || args.includes("-l") || args.includes("--login");
+		const cIdx = args.indexOf("-c");
+		const cmdLine = cIdx !== -1 ? args[cIdx + 1] : undefined;
+		const filteredArgs = args.filter((_, i) =>
+			i !== cIdx && i !== cIdx + 1
+		).filter((a) => a !== "-" && a !== "-l" && a !== "--login");
+		const targetUser = filteredArgs.find((a) => !a.startsWith("-")) ?? "root";
 
-		if (!targetUser) {
-			return { stderr: "su: missing username", exitCode: 1 };
+		// Verify target user exists
+		if (!shell.users.listUsers().includes(targetUser)) {
+			return { stderr: `su: user '${targetUser}' does not exist\n`, exitCode: 1 };
 		}
 
-		if (!users.isSudoer(authUser) && authUser !== "root") {
-			return { stderr: "su: permission denied", exitCode: 1 };
+		// Root switches freely without any password
+		if (authUser === "root") {
+			if (cmdLine) {
+				return runCommand(
+					cmdLine,
+					targetUser,
+					hostname,
+					mode,
+					loginShellFlag ? `/home/${targetUser}` : cwd,
+					shell,
+				);
+			}
+			return {
+				switchUser: targetUser,
+				nextCwd: loginShellFlag ? `/home/${targetUser}` : undefined,
+				exitCode: 0,
+			};
 		}
 
-		if (
-			!users.verifyPassword(targetUser, getArg(args, 1) ?? "") &&
-			authUser !== "root"
-		) {
-			return { stderr: "su: authentication failure", exitCode: 1 };
+		// Non-sudoers denied
+		if (!shell.users.isSudoer(authUser)) {
+			return { stderr: "su: permission denied\n", exitCode: 1 };
 		}
 
+		// Sudoers must enter target user's password via challenge
 		return {
-			switchUser: targetUser,
-			nextCwd: `/home/${targetUser}`,
+			sudoChallenge: {
+				username: targetUser,
+				targetUser,
+				commandLine: cmdLine ?? null,
+				loginShell: loginShellFlag,
+				prompt: "Password: ",
+			},
 			exitCode: 0,
 		};
 	},

package/src/commands/sudo.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import { runCommand } from "./runtime";
 
+/**
+ * Execute a command as another user (superuser by default).
+ * @category users
+ * @params ["[-u user] [-c cmd] [command]"]
+ */
 function parseSudoArgs(args: string[]): {
 	targetUser: string;
 	loginShell: boolean;

package/src/commands/tail.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Output the last part of files or stdin.
+ * @category text
+ * @params ["[-n <lines>] [file...]"]
+ */
 export const tailCommand: ShellModule = {
 	name: "tail",
 	description: "Output last lines",
@@ -9,12 +14,21 @@ export const tailCommand: ShellModule = {
 	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 shortN = args.find((a) => /^-\d+$/.test(a));
+		const n = typeof nArg === "string"
+			? parseInt(nArg, 10)
+			: shortN ? parseInt(shortN.slice(1), 10) : 10;
+		const positionals = args.filter(
+			(a) => !a.startsWith("-") && a !== nArg && a !== String(n),
+		);
 
 		const take = (content: string) => {
 			const lines = content.split("\n");
-			return lines.slice(Math.max(0, lines.length - n)).join("\n");
+			// If content ends with \n, last element is ""; exclude from count
+			const hasTrailingNewline = content.endsWith("\n");
+			const meaningful = hasTrailingNewline ? lines.slice(0, -1) : lines;
+			const sliced = meaningful.slice(Math.max(0, meaningful.length - n));
+			return sliced.join("\n") + (hasTrailingNewline ? "\n" : "");
 		};
 
 		if (positionals.length === 0) {

package/src/commands/tar.ts

@@ -1,32 +1,55 @@
 import type { ShellModule } from "../types/commands";
-import { ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
 
+/**
+ * Archive or extract files with tar and optional gzip compression.
+ * @category archive
+ * @params ["[-czf|-xzf|-tf] <archive> [files...]"]
+ */
 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"),
-					);
+		// Expand combined flags: -czf or czf (bare mode string) → ["-c", "-z", "-f"]
+		const expanded: string[] = [];
+		let foundModeStr = false;
+		for (const a of args) {
+			if (/^-[a-zA-Z]{2,}$/.test(a)) {
+				// -czf style
+				for (const ch of a.slice(1)) expanded.push(`-${ch}`);
+			} else if (!foundModeStr && /^[cxtdru]{1,}[a-zA-Z]*$/.test(a) && !a.includes("/") && !a.startsWith("-")) {
+				// czf bare style (first non-path arg)
+				foundModeStr = true;
+				for (const ch of a) expanded.push(`-${ch}`);
+			} else {
+				expanded.push(a);
+			}
+		}
+
+		const create  = expanded.includes("-c");
+		const extract = expanded.includes("-x");
+		const list    = expanded.includes("-t");
+		const fIdx    = expanded.indexOf("-f");
+		const archiveName = fIdx !== -1
+			? expanded[fIdx + 1]
+			: expanded.find((a) => a.endsWith(".tar") || a.endsWith(".tar.gz") || a.endsWith(".tgz"));
+
+		if (!create && !extract && !list) {
+			return { stderr: "tar: must specify -c, -x, or -t\n", exitCode: 1 };
+		}
 
 		if (!archiveName)
-			return { stderr: "tar: no archive specified", exitCode: 1 };
+			return { stderr: "tar: no archive specified\n", exitCode: 1 };
 		const archivePath = resolvePath(cwd, archiveName);
 
 		if (create) {
-			const fileArgs = args.filter(
-				(a) => !a.startsWith("-") && a !== archiveName,
+			// Skip flags and archive name from file list
+			const skipNext2 = new Set<number>();
+			if (fIdx !== -1) skipNext2.add(fIdx + 1);
+			const fileArgs = expanded.filter((a, i) =>
+				!a.startsWith("-") && a !== archiveName && !skipNext2.has(i),
 			);
 			const entries: Record<string, string> = {};
 			for (const f of fileArgs) {

package/src/commands/tee.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
 
+/**
+ * Read stdin and write to stdout and files simultaneously.
+ * @category text
+ * @params ["[-a] <file...>"]
+ */
 export const teeCommand: ShellModule = {
 	name: "tee",
 	description: "Read stdin, write to stdout and files",

package/src/commands/touch.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Create empty files or update file timestamps.
+ * @category files
+ * @params ["<file>"]
+ */
 export const touchCommand: ShellModule = {
 	name: "touch",
 	description: "Create or update files",

package/src/commands/tr.ts

@@ -1,26 +1,70 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+function unescapeTrSet(s: string): string {
+	return s
+		.replace(/\\n/g, "\n")
+		.replace(/\\t/g, "\t")
+		.replace(/\\r/g, "\r")
+		.replace(/\\\\/g, "\\");
+}
+
+function expandTrSet(s: string): string[] {
+	const chars: string[] = [];
+	const unescaped = unescapeTrSet(s);
+	let i = 0;
+	while (i < unescaped.length) {
+		// Range: a-z, A-Z, 0-9
+		if (i + 2 < unescaped.length && unescaped[i + 1] === "-") {
+			const from = unescaped.charCodeAt(i);
+			const to   = unescaped.charCodeAt(i + 2);
+			if (from <= to) {
+				for (let c = from; c <= to; c++) chars.push(String.fromCharCode(c));
+				i += 3;
+				continue;
+			}
+		}
+		chars.push(unescaped[i]!);
+		i++;
+	}
+	return chars;
+}
+
 export const trCommand: ShellModule = {
 	name: "tr",
 	description: "Translate or delete characters",
 	category: "text",
-	params: ["[-d] <set1> [set2]"],
+	params: ["[-d] [-s] <set1> [set2]"],
 	run: ({ args, stdin }) => {
-		const del = ifFlag(args, ["-d"]);
+		const del     = ifFlag(args, ["-d"]);
+		const squeeze = ifFlag(args, ["-s"]);
 		const positionals = args.filter((a) => !a.startsWith("-"));
-		const set1 = positionals[0] ?? "";
-		const set2 = positionals[1] ?? "";
+		const set1chars = expandTrSet(positionals[0] ?? "");
+		const set2chars = expandTrSet(positionals[1] ?? "");
+
 		let input = stdin ?? "";
+
 		if (del) {
-			for (const c of set1) input = input.split(c).join("");
-		} else if (set2) {
-			for (let i = 0; i < set1.length; i++) {
-				input = input
-					.split(set1[i]!)
-					.join(set2[i] ?? set2[set2.length - 1] ?? "");
+			const deleteSet = new Set(set1chars);
+			input = [...input].filter((c) => !deleteSet.has(c)).join("");
+		} else if (set2chars.length > 0) {
+			// Build translation map
+			const map = new Map<string, string>();
+			for (let i = 0; i < set1chars.length; i++) {
+				map.set(
+					set1chars[i]!,
+					set2chars[i] ?? set2chars[set2chars.length - 1] ?? "",
+				);
 			}
+			input = [...input].map((c) => map.get(c) ?? c).join("");
+		}
+
+		if (squeeze && set2chars.length > 0) {
+			// Squeeze repeated characters in set2
+			const squeezeSet = new Set(set2chars);
+			input = input.replace(/(.)\1+/g, (_, c) => squeezeSet.has(c) ? c : _);
 		}
+
 		return { stdout: input, exitCode: 0 };
 	},
 };

package/src/commands/tree.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Display directory structure in a tree format.
+ * @category navigation
+ * @params ["[path]"]
+ */
 export const treeCommand: ShellModule = {
 	name: "tree",
 	description: "Display directory tree",

package/src/commands/true.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Always return success (exit code 0).
+ * @category shell
+ * @params []
+ */
 export const trueCommand: ShellModule = {
 	name: "true",
 	description: "Return success exit code",
@@ -8,6 +13,11 @@ export const trueCommand: ShellModule = {
 	run: () => ({ exitCode: 0 }),
 };
 
+/**
+ * Always return failure (exit code 1).
+ * @category shell
+ * @params []
+ */
 export const falseCommand: ShellModule = {
 	name: "false",
 	description: "Return failure exit code",

package/src/commands/type.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { resolveModule } from "./registry";
 
+/**
+ * Describe how a command name would be interpreted (builtin, function, or file).
+ * @category shell
+ * @params ["<command...>"]
+ */
 export const typeCommand: ShellModule = {
 	name: "type",
 	description: "Describe how a command would be interpreted",

package/src/commands/uname.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Print system information (kernel name, version, machine type).
+ * @category system
+ * @params ["[-a] [-s] [-r] [-m]"]
+ */
 export const unameCommand: ShellModule = {
 	name: "uname",
 	description: "Print system information",

package/src/commands/uniq.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Report or filter out repeated consecutive lines.
+ * @category text
+ * @params ["[-c] [-d] [-u] [file]"]
+ */
 export const uniqCommand: ShellModule = {
 	name: "uniq",
 	description: "Report or filter out repeated lines",

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)",

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",