typescript-virtual-container 1.3.3 → 1.4.0

package/src/commands/gzip.ts

@@ -2,54 +2,80 @@ 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 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);
-		try {
-			shell.vfs.compressFile(p);
+
+		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 };
-		} catch {
-			return {
-				stderr: `gzip: ${file}: No such file or directory`,
-				exitCode: 1,
-			};
 		}
+
+		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/mkdir.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getArg } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Create one or more directories.
+ * @category files
+ * @params ["<dir>"]
+ */
 export const mkdirCommand: ShellModule = {
 	name: "mkdir",
 	description: "Make directories",

package/src/commands/mv.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Move or rename files and directories.
+ * @category files
+ * @params ["<source> <dest>"]
+ */
 export const mvCommand: ShellModule = {
 	name: "mv",
 	description: "Move or rename files",

package/src/commands/nano.ts

@@ -2,6 +2,11 @@ import * as path from "node:path";
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Simple text editor for editing files.
+ * @category files
+ * @params ["<file>"]
+ */
 export const nanoCommand: ShellModule = {
 	name: "nano",
 	description: "Text editor",

package/src/commands/neofetch.ts

@@ -1,16 +1,18 @@
 import { buildNeofetchOutput } from "../modules/neofetch";
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
-import { getAllEnvVars } from "./set";
 
+/**
+ * Display system information in a decorative format.
+ * @category system
+ * @params ["[--off]"]
+ */
 export const neofetchCommand: ShellModule = {
 	name: "neofetch",
 	description: "System info display",
 	category: "system",
 	params: ["[--off]"],
-	run: ({ args, authUser, hostname, shell }) => {
-		const env = getAllEnvVars(authUser);
-
+	run: ({ args, authUser, hostname, shell, env }) => {
 		if (ifFlag(args, "--help")) {
 			return {
 				stdout: "Usage: neofetch [--off]",
@@ -29,9 +31,9 @@ export const neofetchCommand: ShellModule = {
 			stdout: buildNeofetchOutput({
 				user: authUser,
 				host: hostname,
-				shell: env.SHELL,
+				shell: env.vars.SHELL,
 				shellProps: shell.properties,
-				terminal: env.TERM,
+				terminal: env.vars.TERM,
 				uptimeSeconds: Math.floor((Date.now() - shell.startTime) / 1000),
 				packages: (() => {
 					const count = shell.packageManager?.installedCount() ?? 0;

package/src/commands/passwd.ts

@@ -1,26 +1,49 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * `passwd [username]` — change a virtual user's password.
+ *
+ * - Root can change any user's password.
+ * - Non-root can only change their own password.
+ * - Interactive: emits `passwordChallenge` for hidden-input prompting.
+ * - Non-interactive: reads new password from stdin first line.
+ */
 export const passwdCommand: ShellModule = {
 	name: "passwd",
 	description: "Change user password",
 	category: "users",
-	params: ["<username> <password>"],
-	run: async ({ authUser, args, shell }) => {
-		const [username, password] = args;
-		if (!username || !password) {
-			return {
-				stderr: "passwd: usage: passwd <username> <password>",
-				exitCode: 1,
-			};
-		}
+	params: ["[username]"],
+	run: async ({ authUser, args, shell, stdin }) => {
+		const targetUser = args[0] ?? authUser;
 
-		if (authUser !== "root" && authUser !== username) {
+		// Permission check
+		if (authUser !== "root" && authUser !== targetUser) {
 			return { stderr: "passwd: permission denied", exitCode: 1 };
 		}
 
-		await shell.users.setPassword(username, password);
+		// Target must exist
+		if (!shell.users.listUsers().includes(targetUser)) {
+			return { stderr: `passwd: user '${targetUser}' does not exist`, exitCode: 1 };
+		}
+
+		// Non-interactive: read new password from stdin
+		if (stdin !== undefined && stdin.trim().length > 0) {
+			const password = stdin.trim().split("\n")[0]!;
+			await shell.users.setPassword(targetUser, password);
+			return {
+				stdout: `passwd: password updated successfully\n`,
+				exitCode: 0,
+			};
+		}
+
+		// Interactive: emit password challenge
 		return {
-			stdout: `passwd: password updated for '${username}'`,
+			passwordChallenge: {
+				prompt: "New password: ",
+				confirmPrompt: "Retype new password: ",
+				action: "passwd" as const,
+				targetUsername: targetUser,
+			},
 			exitCode: 0,
 		};
 	},

package/src/commands/ping.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 
+/**
+ * Send ICMP ECHO_REQUEST packets (mock implementation).
+ * @category network
+ * @params ["[-c <count>] <host>"]
+ */
 export const pingCommand: ShellModule = {
 	name: "ping",
 	description: "Send ICMP ECHO_REQUEST (mock)",

package/src/commands/printf.ts

@@ -50,35 +50,47 @@ function renderPrintf(fmt: string, args: string[]): string {
 			}
 		}
 		if (fmt[i] === "%" && i + 1 < fmt.length) {
-			// Optional width/precision: %[-][width][.prec]spec
 			let j = i + 1;
-			if (fmt[j] === "-") j++;
-			while (j < fmt.length && /\d/.test(fmt[j]!)) j++;
+			let leftAlign = false; if (fmt[j] === "-") { leftAlign = true; j++; }
+			let zeroPad = false; if (fmt[j] === "0") { zeroPad = true; j++; }
+			let width = 0;
+			while (j < fmt.length && /\d/.test(fmt[j]!)) { width = width * 10 + parseInt(fmt[j]!, 10); j++; }
+			let precision = -1;
 			if (fmt[j] === ".") {
-				j++;
-				while (j < fmt.length && /\d/.test(fmt[j]!)) j++;
+				j++; precision = 0;
+				while (j < fmt.length && /\d/.test(fmt[j]!)) { precision = precision * 10 + parseInt(fmt[j]!, 10); j++; }
 			}
 			const spec = fmt[j];
 			const arg = args[argIdx++] ?? "";
+			const pad = (s: string, ch = " "): string => {
+				if (width <= 0 || s.length >= width) return s;
+				const fill = ch.repeat(width - s.length);
+				return leftAlign ? s + fill : fill + s;
+			};
 			switch (spec) {
-				case "s":
-					out += arg;
+				case "s": {
+					let val = String(arg);
+					if (precision >= 0) val = val.slice(0, precision);
+					out += pad(val);
 					break;
+				}
 				case "d":
 				case "i":
-					out += String(parseInt(arg, 10) || 0);
+					out += pad(String(parseInt(arg, 10) || 0), zeroPad ? "0" : " ");
 					break;
-				case "f":
-					out += String(parseFloat(arg) || 0);
+				case "f": {
+					const prec = precision >= 0 ? precision : 6;
+					out += pad((parseFloat(arg) || 0).toFixed(prec));
 					break;
+				}
 				case "o":
-					out += (parseInt(arg, 10) || 0).toString(8);
+					out += pad((parseInt(arg, 10) || 0).toString(8), zeroPad ? "0" : " ");
 					break;
 				case "x":
-					out += (parseInt(arg, 10) || 0).toString(16);
+					out += pad((parseInt(arg, 10) || 0).toString(16), zeroPad ? "0" : " ");
 					break;
 				case "X":
-					out += (parseInt(arg, 10) || 0).toString(16).toUpperCase();
+					out += pad((parseInt(arg, 10) || 0).toString(16).toUpperCase(), zeroPad ? "0" : " ");
 					break;
 				case "%":
 					out += "%";
@@ -98,6 +110,11 @@ function renderPrintf(fmt: string, args: string[]): string {
 	return out;
 }
 
+/**
+ * Format and print data to stdout.
+ * @category shell
+ * @params ["<format> [args...]"]
+ */
 export const printfCommand: ShellModule = {
 	name: "printf",
 	description: "Format and print data",

package/src/commands/ps.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Report process status with various formatting options.
+ * @category system
+ * @params ["[-a] [-u] [-x] [aux]"]
+ */
 export const psCommand: ShellModule = {
 	name: "ps",
 	description: "Report process status",

package/src/commands/read.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Read a line from stdin into one or more variables.
+ * @category shell
+ * @params ["[-r] [-p prompt] <var...>"]
+ */
 export const readCommand: ShellModule = {
 	name: "read",
 	description: "Read a line from stdin into variables",

package/src/commands/registry.ts

@@ -35,7 +35,8 @@ import { hostnameCommand } from "./hostname";
 import { htopCommand } from "./htop";
 import { idCommand } from "./id";
 import { killCommand } from "./kill";
-import { lnCommand } from "./ln";
+import { lnCommand, readlinkCommand } from "./ln";
+import { statCommand } from "./stat";
 import { lsCommand } from "./ls";
 import { lsbReleaseCommand } from "./lsb-release";
 import { manCommand } from "./man";
@@ -96,7 +97,9 @@ const BASE_COMMANDS: ShellModule[] = [
 	cpCommand,
 	mvCommand,
 	lnCommand,
+	readlinkCommand,
 	chmodCommand,
+	statCommand,
 	findCommand,
 	// Text processing
 	grepCommand,

package/src/commands/rm.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getArg, ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Remove files or directories from the filesystem.
+ * @category files
+ * @params ["[-r|-rf] <path>"]
+ */
 export const rmCommand: ShellModule = {
 	name: "rm",
 	description: "Remove files or directories",

package/src/commands/runtime.ts

@@ -8,69 +8,9 @@ import type {
     ShellEnv,
 } from "../types/commands";
 import { expandAsync } from "../utils/expand";
+import { tokenizeCommand } from "../utils/tokenize";
 import { resolveModule } from "./registry";
 
-// ── Tokenize command input respecting quotes ──────────────────────────────────
-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;
-}
-
 export function makeDefaultEnv(authUser: string, hostname: string): ShellEnv {
 	return {
 		vars: {

package/src/commands/sed.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getFlag, ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
 
+/**
+ * Stream editor for filtering and transforming text lines.
+ * @category text
+ * @params ["-e <expr> [file]", "s/pattern/replace/[g]"]
+ */
 export const sedCommand: ShellModule = {
 	name: "sed",
 	description: "Stream editor for filtering and transforming text",

package/src/commands/set.ts

@@ -1,30 +1,11 @@
 /** biome-ignore-all lint/style/useNamingConvention: env variables */
 import type { ShellModule } from "../types/commands";
 
-// 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",
-	TERM: "xterm-256color",
-	USER: "user",
-};
-
-/** @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> {
-	_globalEnv.USER = authUser;
-	_globalEnv.HOME = `/home/${authUser}`;
-	return { ..._globalEnv };
-}
-
+/**
+ * Display or set shell variables and options.
+ * @category shell
+ * @params ["[VAR=value]"]
+ */
 export const setCommand: ShellModule = {
 	name: "set",
 	description: "Display or set shell variables",

package/src/commands/sh.ts

@@ -1,7 +1,7 @@
 import type {
-    CommandContext,
-    CommandResult,
-    ShellModule,
+	CommandContext,
+	CommandResult,
+	ShellModule,
 } from "../types/commands";
 import { expandAsync } from "../utils/expand";
 import { ifFlag } from "./command-helpers";
@@ -286,6 +286,12 @@ async function runBlocks(
 	return { ...lastResult, stdout: output.trim() || lastResult.stdout };
 }
 
+/**
+ * Execute shell scripts or commands with a minimal shell interpreter.
+ * Supports if/elif/else, for loops, while loops, and variable expansion.
+ * @category shell
+ * @params ["-c <script>", "[<file>]"]
+ */
 export const shCommand: ShellModule = {
 	name: "sh",
 	aliases: ["bash"],