typescript-virtual-container 1.3.4 → 1.4.1

package/src/commands/deluser.ts

@@ -1,21 +1,98 @@
-import type { ShellModule } from "../types/commands";
+import type { CommandResult, ShellModule } from "../types/commands";
+import type { VirtualShell } from "../VirtualShell";
 
+/**
+ * Delete a user. Root-only.
+ *
+ * Without `-f`: prompts for confirmation — the user must type the exact
+ * username to proceed.
+ *
+ * With `-f` / `--force`: deletes without confirmation.
+ *
+ * Usage:
+ *   deluser <username>
+ *   deluser -f <username>
+ */
 export const deluserCommand: ShellModule = {
 	name: "deluser",
 	description: "Delete a user",
 	category: "users",
-	params: ["<username>"],
+	params: ["[-f] <username>"],
 	run: async ({ authUser, args, shell }) => {
 		if (authUser !== "root") {
-			return { stderr: "deluser: permission denied", exitCode: 1 };
+			return { stderr: "deluser: permission denied\n", exitCode: 1 };
 		}
 
-		const [username] = args;
+		const force =
+			args.includes("-f") ||
+			args.includes("--force") ||
+			args.includes("-y");
+		const username = args.find((a) => !a.startsWith("-"));
+
 		if (!username) {
-			return { stderr: "deluser: usage: deluser <username>", exitCode: 1 };
+			return {
+				stderr: "Usage: deluser [-f] <username>\n",
+				exitCode: 1,
+			};
+		}
+
+		if (!shell.users.listUsers().includes(username)) {
+			return {
+				stderr: `deluser: user '${username}' does not exist\n`,
+				exitCode: 1,
+			};
+		}
+
+		if (username === "root") {
+			return {
+				stderr: "deluser: cannot remove the root account\n",
+				exitCode: 1,
+			};
 		}
 
-		await shell.users.deleteUser(username);
-		return { stdout: `deluser: user '${username}' deleted`, exitCode: 0 };
+		// Force mode — delete without confirmation
+		if (force) {
+			await shell.users.deleteUser(username);
+			return {
+				stdout: `Removing user '${username}' ...\ndeluser: done.\n`,
+				exitCode: 0,
+			};
+		}
+
+		// Interactive confirmation
+		const onPassword = async (
+			input: string,
+			sh: VirtualShell,
+		): Promise<{ result: CommandResult | null; nextPrompt?: string }> => {
+			if (input.trim() !== username) {
+				return {
+					result: {
+						stderr: "deluser: confirmation did not match — user not deleted\n",
+						exitCode: 1,
+					},
+				};
+			}
+
+			await sh.users.deleteUser(username);
+			return {
+				result: {
+					stdout: `Removing user '${username}' ...\ndeluser: done.\n`,
+					exitCode: 0,
+				},
+			};
+		};
+
+		return {
+			sudoChallenge: {
+				username,
+				targetUser: username,
+				commandLine: null,
+				loginShell: false,
+				prompt: `Warning: deleting user '${username}'.\nType the username to confirm: `,
+				mode: "confirm",
+				onPassword,
+			},
+			exitCode: 0,
+		};
 	},
 };

package/src/commands/df.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Report filesystem disk space usage.
+ * @category system
+ * @params ["[-h]"]
+ */
 export const dfCommand: ShellModule = {
 	name: "df",
 	description: "Report filesystem disk space usage",

package/src/commands/du.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
 
+/**
+ * Estimate file and directory space usage.
+ * @category system
+ * @params ["[-h] [-s] [path]"]
+ */
 export const duCommand: ShellModule = {
 	name: "du",
 	description: "Estimate file space usage",

package/src/commands/export.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Set or display shell environment variables for child processes.
+ * @category shell
+ * @params ["[VAR=value]"]
+ */
 export const exportCommand: ShellModule = {
 	name: "export",
 	description: "Set shell environment variable",

package/src/commands/grep.ts

@@ -14,12 +14,15 @@ export const grepCommand: ShellModule = {
 	params: ["[-i] [-v] [-n] [-r] <pattern> [file...]"],
 	run: ({ authUser, shell, cwd, args, stdin }) => {
 		const { flags, positionals } = parseArgs(args, {
-			flags: ["-i", "-v", "-n", "-r"],
+			flags: ["-i", "-v", "-n", "-r", "-c", "-l", "-L", "-q", "--quiet", "--silent"],
 		});
-		const caseInsensitive = flags.has("-i");
-		const invertMatch = flags.has("-v");
-		const showLineNumbers = flags.has("-n");
-		const recursive = flags.has("-r");
+		const caseInsensitive  = flags.has("-i");
+		const invertMatch      = flags.has("-v");
+		const showLineNumbers  = flags.has("-n");
+		const recursive        = flags.has("-r");
+		const countOnly        = flags.has("-c");
+		const filesWithMatches = flags.has("-l");
+		const quiet            = flags.has("-q") || flags.has("--quiet") || flags.has("--silent");
 		const pattern = positionals[0];
 		const files = positionals.slice(1);
 
@@ -73,7 +76,10 @@ export const grepCommand: ShellModule = {
 
 		if (files.length === 0) {
 			if (!stdin) return { stdout: "", exitCode: 1 };
-			results.push(...matchLines(stdin));
+			const matched = matchLines(stdin);
+			if (countOnly) return { stdout: `${matched.length}\n`, exitCode: matched.length > 0 ? 0 : 1 };
+			if (quiet) return { exitCode: matched.length > 0 ? 0 : 1 };
+			results.push(...matched);
 		} else {
 			const resolvedPaths = files.flatMap((f) => {
 				const target = resolvePath(cwd, f);
@@ -85,7 +91,14 @@ export const grepCommand: ShellModule = {
 					assertPathAccess(authUser, filePath, "grep");
 					const content = shell.vfs.readFile(filePath);
 					const prefix = resolvedPaths.length > 1 ? `${file}:` : "";
-					results.push(...matchLines(content, prefix));
+					const matched = matchLines(content, prefix);
+					if (countOnly) {
+						results.push(resolvedPaths.length > 1 ? `${file}:${matched.length}` : String(matched.length));
+					} else if (filesWithMatches) {
+						if (matched.length > 0) results.push(file);
+					} else {
+						results.push(...matched);
+					}
 				} catch {
 					return {
 						stderr: `grep: ${file}: No such file or directory`,
@@ -96,7 +109,7 @@ export const grepCommand: ShellModule = {
 		}
 
 		return {
-			stdout: results.length > 0 ? results.join("\n") : "",
+			stdout: results.length > 0 ? `${results.join("\n")}\n` : "",
 			exitCode: results.length > 0 ? 0 : 1,
 		};
 	},

package/src/commands/groups.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Print group memberships for a user.
+ * @category system
+ * @params ["[user]"]
+ */
 export const groupsCommand: ShellModule = {
 	name: "groups",
 	description: "Print group memberships",

package/src/commands/gzip.ts

@@ -2,54 +2,87 @@ import type { ShellModule } from "../types/commands";
 import { resolvePath } from "./helpers";
 
 /**
- * Compress files using gzip (stores in VFS as compressed content).
+ * Compress files using gzip — renames file to `<file>.gz`, removes original.
  * @category archive
- * @params ["<file>"]
  */
 export const gzipCommand: ShellModule = {
 	name: "gzip",
 	description: "Compress files",
 	category: "archive",
-	params: ["<file>"],
+	params: ["[-k] [-d] <file>"],
 	run: ({ shell, cwd, args }) => {
-		const file = args[0];
-		if (!file) return { stderr: "gzip: no file specified", exitCode: 1 };
-		const p = resolvePath(cwd, file);
-		try {
-			shell.vfs.compressFile(p);
-			return { exitCode: 0 };
-		} catch {
+		if (!shell.packageManager.isInstalled("gzip")) {
 			return {
-				stderr: `gzip: ${file}: No such file or directory`,
-				exitCode: 1,
+				stderr:
+					"bash: gzip: command not found\nHint: install it with: apt install gzip\n",
+				exitCode: 127,
 			};
 		}
+		const keepOrig = args.includes("-k") || args.includes("--keep");
+		const decompress = args.includes("-d");
+		const file = args.find((a) => !a.startsWith("-"));
+		if (!file) return { stderr: "gzip: no file specified\n", exitCode: 1 };
+
+		const p = resolvePath(cwd, file);
+
+		if (decompress) {
+			// gzip -d = gunzip
+			if (!file.endsWith(".gz")) {
+				return { stderr: `gzip: ${file}: unknown suffix -- ignored\n`, exitCode: 1 };
+			}
+			if (!shell.vfs.exists(p)) {
+				return { stderr: `gzip: ${file}: No such file or directory\n`, exitCode: 1 };
+			}
+			const content = shell.vfs.readFile(p);
+			const dest = p.slice(0, -3);
+			shell.vfs.writeFile(dest, content);
+			if (!keepOrig) shell.vfs.remove(p);
+			return { exitCode: 0 };
+		}
+
+		if (!shell.vfs.exists(p)) {
+			return { stderr: `gzip: ${file}: No such file or directory\n`, exitCode: 1 };
+		}
+		if (file.endsWith(".gz")) {
+			return { stderr: `gzip: ${file}: already has .gz suffix -- unchanged\n`, exitCode: 1 };
+		}
+
+		const rawContent = shell.vfs.readFileRaw(p);
+		const gzPath = `${p}.gz`;
+		shell.vfs.writeFile(gzPath, rawContent, { compress: true });
+		if (!keepOrig) shell.vfs.remove(p);
+		return { exitCode: 0 };
 	},
 };
 
+/**
+ * Decompress gzip files — renames `<file>.gz` to `<file>`, removes original.
+ * @category archive
+ */
 export const gunzipCommand: ShellModule = {
-	/**
-	 * Decompress gzip files (or zcat alias).
-	 * @category archive
-	 * @params ["<file>"]
-	 */
 	name: "gunzip",
 	description: "Decompress files",
 	category: "archive",
-	params: ["<file>"],
 	aliases: ["zcat"],
+	params: ["[-k] <file>"],
 	run: ({ shell, cwd, args }) => {
-		const file = args[0];
-		if (!file) return { stderr: "gunzip: no file specified", exitCode: 1 };
+		const keepOrig = args.includes("-k") || args.includes("--keep");
+		const file = args.find((a) => !a.startsWith("-"));
+		if (!file) return { stderr: "gunzip: no file specified\n", exitCode: 1 };
+
 		const p = resolvePath(cwd, file);
-		try {
-			shell.vfs.decompressFile(p);
-			return { exitCode: 0 };
-		} catch {
-			return {
-				stderr: `gunzip: ${file}: No such file or directory`,
-				exitCode: 1,
-			};
+
+		if (!shell.vfs.exists(p)) {
+			return { stderr: `gunzip: ${file}: No such file or directory\n`, exitCode: 1 };
 		}
+		if (!file.endsWith(".gz")) {
+			return { stderr: `gunzip: ${file}: unknown suffix -- ignored\n`, exitCode: 1 };
+		}
+
+		const content = shell.vfs.readFile(p);
+		const dest = p.slice(0, -3);
+		shell.vfs.writeFile(dest, content);
+		if (!keepOrig) shell.vfs.remove(p);
+		return { exitCode: 0 };
 	},
 };

package/src/commands/head.ts

@@ -14,11 +14,21 @@ export const headCommand: 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);
+		// Support both -n N and -N shorthand (head -2, head -10)
+		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) =>
-			content.split("\n").slice(0, n).join("\n");
+		const take = (content: string) => {
+			const lines = content.split("\n");
+			// Preserve trailing newline
+			const sliced = lines.slice(0, n);
+			return sliced.join("\n") + (content.endsWith("\n") && sliced.length === lines.slice(0, n).length ? "\n" : "");
+		};
 
 		if (positionals.length === 0) {
 			return { stdout: take(stdin ?? ""), exitCode: 0 };

package/src/commands/htop.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Interactive system monitor (requires terminal interaction).
+ * @category system
+ * @params []
+ */
 export const htopCommand: ShellModule = {
 	name: "htop",
 	description: "System monitor",

package/src/commands/kill.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Send a signal to a process by PID.
+ * @category system
+ * @params ["[-9] <pid>"]
+ */
 export const killCommand: ShellModule = {
 	name: "kill",
 	description: "Send signal to process",

package/src/commands/ln.ts

@@ -47,3 +47,25 @@ export const lnCommand: ShellModule = {
 		}
 	},
 };
+
+/** Shell command: print the value of a symbolic link. */
+export const readlinkCommand: ShellModule = {
+	name: "readlink",
+	description: "Print resolved path of symbolic link",
+	category: "files",
+	params: ["[-f] <path>"],
+	run: ({ shell, cwd, args }) => {
+		const follow = args.includes("-f") || args.includes("-e");
+		const target = args.find((a) => !a.startsWith("-"));
+		if (!target) return { stderr: "readlink: missing operand\n", exitCode: 1 };
+		const p = resolvePath(cwd, target);
+		if (!shell.vfs.exists(p)) {
+			return { stderr: `readlink: ${target}: No such file or directory\n`, exitCode: 1 };
+		}
+		if (!shell.vfs.isSymlink(p)) {
+			return { stderr: `readlink: ${target}: not a symbolic link\n`, exitCode: 1 };
+		}
+		const resolved = shell.vfs.resolveSymlink(follow ? p : p);
+		return { stdout: `${resolved}\n`, exitCode: 0 };
+	},
+};

package/src/commands/ls.ts

@@ -39,6 +39,23 @@ export const lsCommand: ShellModule = {
 		});
 		const target = resolvePath(cwd, targetArg ?? cwd);
 		assertPathAccess(authUser, target, "ls");
+
+		// If target is a file, show its info directly (ls -l /etc/passwd)
+		if (shell.vfs.exists(target)) {
+			const st = shell.vfs.stat(target);
+			if (st.type === "file" || shell.vfs.isSymlink(target)) {
+				if (longFormat) {
+					const name = target.split("/").pop() ?? target;
+					const size = st.type === "file" ? st.size : 0;
+					return {
+						stdout: `${formatPermissions(st.mode, false)} 1 root root ${size} ${formatDate(st.updatedAt)} ${name}\n`,
+						exitCode: 0,
+					};
+				}
+				return { stdout: target.split("/").pop() ?? target, exitCode: 0 };
+			}
+		}
+
 		const items = shell.vfs
 			.list(target)
 			.filter((name) => showHidden || !name.startsWith("."));

package/src/commands/lsb-release.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Print Linux distribution information.
+ * @category system
+ * @params ["[-a] [-i] [-d] [-r] [-c]"]
+ */
 export const lsbReleaseCommand: ShellModule = {
 	name: "lsb_release",
 	description: "Print distribution-specific information",

package/src/commands/man.ts

@@ -1,154 +1,49 @@
 import type { ShellModule } from "../types/commands";
 
-const MAN_PAGES: Record<string, string> = {
-	ls: `LS(1)                    User Commands                    LS(1)
-
-NAME
-       ls - list directory contents
-
-SYNOPSIS
-       ls [OPTION]... [FILE]...
-
-DESCRIPTION
-       List information about the FILEs (the current directory by default).
-
-OPTIONS
-       -l     use a long listing format
-       -a     do not ignore entries starting with .
-       -h     with -l, print human readable sizes
-       -r     reverse order while sorting
-       -t     sort by modification time
-
-AUTHOR
-       Written by Richard M. Stallman and David MacKenzie.`,
-
-	cat: `CAT(1)                   User Commands                    CAT(1)
-
-NAME
-       cat - concatenate files and print on the standard output
-
-SYNOPSIS
-       cat [OPTION]... [FILE]...
-
-DESCRIPTION
-       Concatenate FILE(s) to standard output.
-
-OPTIONS
-       -n, --number          number all output lines
-       -b, --number-nonblank number nonempty output lines`,
-
-	grep: `GREP(1)                  User Commands                    GREP(1)
-
-NAME
-       grep, egrep, fgrep - print lines that match patterns
-
-SYNOPSIS
-       grep [OPTION]... PATTERNS [FILE]...
-
-OPTIONS
-       -i, --ignore-case     ignore case distinctions in patterns and data
-       -v, --invert-match    select non-matching lines
-       -n, --line-number     print line number with output lines
-       -r, --recursive       read all files under each directory, recursively`,
-
-	apt: `APT(8)                   APT                             APT(8)
-
-NAME
-       apt - command-line interface
-
-SYNOPSIS
-       apt [options] command
-
-DESCRIPTION
-       apt provides a high-level commandline interface for the package
-       management system.
-
-COMMANDS
-       install pkg...   Install packages
-       remove pkg...    Remove packages
-       update           Download package information
-       upgrade          Upgrade installed packages
-       search term      Search in package descriptions
-       show pkg         Show package information
-       list             List packages`,
-
-	ssh: `SSH(1)                   OpenSSH                          SSH(1)
-
-NAME
-       ssh - OpenSSH remote login client
-
-SYNOPSIS
-       ssh [-p port] [user@]hostname [command]
-
-DESCRIPTION
-       ssh (SSH client) is a program for logging into a remote machine and
-       for executing commands on a remote machine.`,
-
-	curl: `CURL(1)                  User Commands                    CURL(1)
-
-NAME
-       curl - transfer a URL
-
-SYNOPSIS
-       curl [options / URLs]
-
-DESCRIPTION
-       curl is a tool for transferring data with URL syntax.
-
-OPTIONS
-       -o, --output <file>     Write output to <file>
-       -X, --request <method>  Specify request method
-       -d, --data <data>       HTTP POST data
-       -H, --header <header>   Pass custom header
-       -s, --silent            Silent mode
-       -I, --head              Show document info only
-       -L, --location          Follow redirects
-       -v, --verbose           Make the operation more talkative`,
-
-	chmod: `CHMOD(1)                 User Commands                    CHMOD(1)
-
-NAME
-       chmod - change file mode bits
-
-SYNOPSIS
-       chmod [OPTION]... MODE[,MODE]... FILE...
-       chmod [OPTION]... OCTAL-MODE FILE...
-
-DESCRIPTION
-       Change the file mode bits of each given file according to MODE.
-
-EXAMPLES
-       chmod 755 script.sh      rwxr-xr-x
-       chmod 644 file.txt       rw-r--r--
-       chmod +x script.sh       add execute permission`,
-
-	tar: `TAR(1)                   GNU tar Manual                   TAR(1)
-
-NAME
-       tar - an archiving utility
-
-SYNOPSIS
-       tar [OPTION...] [FILE]...
-
-DESCRIPTION
-       tar saves many files together into a single tape or disk archive,
-       and can restore individual files from the archive.
-
-OPTIONS
-       -c, --create           create a new archive
-       -x, --extract          extract files from an archive
-       -z, --gzip             filter the archive through gzip
-       -f, --file=ARCHIVE     use archive file or device ARCHIVE
-       -v, --verbose          verbosely list files processed
-       -t, --list             list the contents of an archive`,
+const MANUAL_ALIASES: Record<string, string> = {
+	gunzip: "gzip",
 };
 
+const manualCache = new Map<string, string | null>();
+const manualsBaseUrl = new URL("./manuals/", import.meta.url);
+
+async function dynamicImport(specifier: string): Promise<unknown> {
+	const importer = new Function(
+		"moduleName",
+		"return import(moduleName)",
+	) as (moduleName: string) => Promise<unknown>;
+	return importer(specifier);
+}
+
+async function loadBundledManual(commandName: string): Promise<string | null> {
+	const normalized = commandName.toLowerCase();
+	const lookupName = MANUAL_ALIASES[normalized] ?? normalized;
+	const cacheKey = `builtin:${lookupName}`;
+	if (manualCache.has(cacheKey)) {
+		return manualCache.get(cacheKey) ?? null;
+	}
+
+	try {
+		const fsModule = (await dynamicImport("node:fs/promises")) as {
+			readFile: (path: URL, encoding: "utf8") => Promise<string>;
+		};
+		const manualUrl = new URL(`${lookupName}.txt`, manualsBaseUrl);
+		const content = await fsModule.readFile(manualUrl, "utf8");
+		const page = content.replace(/\n$/, "");
+		manualCache.set(cacheKey, page);
+		return page;
+	} catch {
+		manualCache.set(cacheKey, null);
+		return null;
+	}
+}
+
 export const manCommand: ShellModule = {
 	name: "man",
 	description: "Interface to the system reference manuals",
 	category: "shell",
 	params: ["<command>"],
-	run: ({ args, shell }) => {
+	run: async ({ args, shell }) => {
 		const name = args[0];
 		if (!name) return { stderr: "What manual page do you want?", exitCode: 1 };
 
@@ -158,7 +53,7 @@ export const manCommand: ShellModule = {
 			return { stdout: shell.vfs.readFile(manPath), exitCode: 0 };
 		}
 
-		const page = MAN_PAGES[name.toLowerCase()];
+		const page = await loadBundledManual(name);
 		if (page) return { stdout: page, exitCode: 0 };
 
 		return { stderr: `No manual entry for ${name}`, exitCode: 16 };

package/src/commands/manuals/adduser.txt

@@ -0,0 +1,11 @@
+ADDUSER(8)                User Commands                ADDUSER(8)
+
+NAME
+       adduser - add a user to the system
+
+SYNOPSIS
+       adduser USERNAME
+
+DESCRIPTION
+       Create a new user account with a home directory.
+       In this environment, prompts for a password interactively.

package/src/commands/manuals/apt-cache.txt

@@ -0,0 +1,12 @@
+APT-CACHE(8)             APT                        APT-CACHE(8)
+
+NAME
+       apt-cache - query APT package cache
+
+SYNOPSIS
+       apt-cache command [args]
+
+COMMANDS
+       search term    search package names/descriptions
+       show pkg       show package metadata
+       policy pkg     show package policy and candidate versions