typescript-virtual-container 1.3.4 → 1.4.1

package/src/commands/manuals/sleep.txt

@@ -0,0 +1,10 @@
+SLEEP(1)                 User Commands                   SLEEP(1)
+
+NAME
+       sleep - delay for a specified amount of time
+
+SYNOPSIS
+       sleep NUMBER
+
+DESCRIPTION
+       Pause execution for NUMBER seconds.

package/src/commands/manuals/sort.txt

@@ -0,0 +1,12 @@
+SORT(1)                  User Commands                    SORT(1)
+
+NAME
+       sort - sort lines of text files
+
+SYNOPSIS
+       sort [OPTION]... [FILE]...
+
+OPTIONS
+       -r     reverse the result of comparisons
+       -n     compare according to string numerical value
+       -u     output only the first of an equal run

package/src/commands/manuals/source.txt

@@ -0,0 +1,11 @@
+SOURCE(1)                 Shell Builtins                SOURCE(1)
+
+NAME
+       source - execute commands from a file in the current shell
+
+SYNOPSIS
+       source FILE
+       . FILE
+
+DESCRIPTION
+       Read and execute commands from FILE in the current shell context.

package/src/commands/manuals/ssh.txt

@@ -0,0 +1,11 @@
+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.

package/src/commands/manuals/stat.txt

@@ -0,0 +1,10 @@
+STAT(1)                  User Commands                    STAT(1)
+
+NAME
+       stat - display file status
+
+SYNOPSIS
+       stat [OPTION]... FILE...
+
+OPTIONS
+       -c, --format=FORMAT   use the specified output format

package/src/commands/manuals/su.txt

@@ -0,0 +1,13 @@
+SU(1)                    User Commands                      SU(1)
+
+NAME
+       su - run a command with substitute user and group ID
+
+SYNOPSIS
+       su [OPTION]... [USER]
+
+OPTIONS
+       -           start a login shell
+
+DESCRIPTION
+       Switch to another user account in the current session.

package/src/commands/manuals/sudo.txt

@@ -0,0 +1,11 @@
+SUDO(8)                   User Commands                   SUDO(8)
+
+NAME
+       sudo - execute a command as another user
+
+SYNOPSIS
+       sudo [OPTION]... COMMAND [ARG]...
+
+OPTIONS
+       -i          run login shell as target user
+       -u USER     run command as USER

package/src/commands/manuals/tail.txt

@@ -0,0 +1,10 @@
+TAIL(1)                  User Commands                    TAIL(1)
+
+NAME
+       tail - output the last part of files
+
+SYNOPSIS
+       tail [OPTION]... [FILE]...
+
+OPTIONS
+       -n, --lines=[+]NUM    output the last NUM lines

package/src/commands/manuals/tar.txt

@@ -0,0 +1,19 @@
+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

package/src/commands/manuals/tee.txt

@@ -0,0 +1,10 @@
+TEE(1)                   User Commands                     TEE(1)
+
+NAME
+       tee - read from standard input and write to standard output and files
+
+SYNOPSIS
+       tee [OPTION]... [FILE]...
+
+OPTIONS
+       -a     append to the given FILEs, do not overwrite

package/src/commands/manuals/test.txt

@@ -0,0 +1,11 @@
+TEST(1)                   Shell Builtins                  TEST(1)
+
+NAME
+       test - check file types and compare values
+
+SYNOPSIS
+       test EXPRESSION
+       [ EXPRESSION ]
+
+DESCRIPTION
+       Evaluate conditional expressions for scripts and shell logic.

package/src/commands/manuals/touch.txt

@@ -0,0 +1,11 @@
+TOUCH(1)                 User Commands                  TOUCH(1)
+
+NAME
+       touch - change file timestamps / create file
+
+SYNOPSIS
+       touch FILE...
+
+DESCRIPTION
+       Update access and modification times.
+       If FILE does not exist, create an empty file.

package/src/commands/manuals/tr.txt

@@ -0,0 +1,10 @@
+TR(1)                    User Commands                      TR(1)
+
+NAME
+       tr - translate or delete characters
+
+SYNOPSIS
+       tr [OPTION]... SET1 [SET2]
+
+OPTIONS
+       -d     delete characters in SET1 instead of translating

package/src/commands/manuals/trap.txt

@@ -0,0 +1,10 @@
+TRAP(1)                  Shell Builtins                   TRAP(1)
+
+NAME
+       trap - trap signals and other events
+
+SYNOPSIS
+       trap [ACTION] [SIGNAL]...
+
+DESCRIPTION
+       Define or clear handlers for shell signals and EXIT.

package/src/commands/manuals/true.txt

@@ -0,0 +1,10 @@
+TRUE(1)                  User Commands                    TRUE(1)
+
+NAME
+       true - do nothing, successfully
+
+SYNOPSIS
+       true
+
+DESCRIPTION
+       Exit with a status code indicating success (0).

package/src/commands/manuals/type.txt

@@ -0,0 +1,10 @@
+TYPE(1)                   Shell Builtins                  TYPE(1)
+
+NAME
+       type - display how a command name is interpreted
+
+SYNOPSIS
+       type NAME...
+
+DESCRIPTION
+       Indicate whether NAME is a shell builtin, alias, or found in PATH.

package/src/commands/manuals/uname.txt

@@ -0,0 +1,12 @@
+UNAME(1)                 User Commands                  UNAME(1)
+
+NAME
+       uname - print system information
+
+SYNOPSIS
+       uname [OPTION]...
+
+OPTIONS
+       -a     print all information
+       -r     print kernel release
+       -m     print machine hardware name

package/src/commands/manuals/uniq.txt

@@ -0,0 +1,12 @@
+UNIQ(1)                  User Commands                    UNIQ(1)
+
+NAME
+       uniq - report or omit repeated lines
+
+SYNOPSIS
+       uniq [OPTION]... [INPUT [OUTPUT]]
+
+OPTIONS
+       -c     prefix lines by the number of occurrences
+       -d     only print duplicate lines
+       -u     only print unique lines

package/src/commands/manuals/unset.txt

@@ -0,0 +1,10 @@
+UNSET(1)                 Shell Builtins                  UNSET(1)
+
+NAME
+       unset - unset values and attributes of shell variables
+
+SYNOPSIS
+       unset NAME...
+
+DESCRIPTION
+       Remove one or more shell variables from the current environment.

package/src/commands/manuals/uptime.txt

@@ -0,0 +1,11 @@
+UPTIME(1)                User Commands                  UPTIME(1)
+
+NAME
+       uptime - tell how long the system has been running
+
+SYNOPSIS
+       uptime [OPTION]
+
+OPTIONS
+       -p     show uptime in a pretty format
+       -s     show system up since time

package/src/commands/manuals/wc.txt

@@ -0,0 +1,12 @@
+WC(1)                    User Commands                      WC(1)
+
+NAME
+       wc - print newline, word, and byte counts for each file
+
+SYNOPSIS
+       wc [OPTION]... [FILE]...
+
+OPTIONS
+       -l     print the newline counts
+       -w     print the word counts
+       -c     print the byte counts

package/src/commands/manuals/wget.txt

@@ -0,0 +1,12 @@
+WGET(1)                  User Commands                    WGET(1)
+
+NAME
+       wget - non-interactive network downloader
+
+SYNOPSIS
+       wget [OPTION]... [URL]...
+
+OPTIONS
+       -O FILE    write documents to FILE
+       -P DIR     save files to DIR
+       -q         quiet mode

package/src/commands/manuals/which.txt

@@ -0,0 +1,10 @@
+WHICH(1)                 User Commands                  WHICH(1)
+
+NAME
+       which - locate a command
+
+SYNOPSIS
+       which COMMAND...
+
+DESCRIPTION
+       Print the path of COMMAND found in $PATH.

package/src/commands/manuals/whoami.txt

@@ -0,0 +1,10 @@
+WHOAMI(1)                User Commands                 WHOAMI(1)
+
+NAME
+       whoami - print effective user name
+
+SYNOPSIS
+       whoami
+
+DESCRIPTION
+       Print the user name associated with the current effective user ID.

package/src/commands/manuals/xargs.txt

@@ -0,0 +1,10 @@
+XARGS(1)                 User Commands                   XARGS(1)
+
+NAME
+       xargs - build and execute command lines from standard input
+
+SYNOPSIS
+       xargs [COMMAND [INITIAL-ARGS]]
+
+DESCRIPTION
+       Read items from stdin and execute COMMAND with those items as arguments.

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,25 @@
 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 (!shell.packageManager.isInstalled("neofetch")) {
+			return {
+				stderr:
+					"bash: neofetch: command not found\nHint: install it with: apt install neofetch\n",
+				exitCode: 127,
+			};
+		}
 		if (ifFlag(args, "--help")) {
 			return {
 				stdout: "Usage: neofetch [--off]",
@@ -29,9 +38,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",