typescript-virtual-container 1.2.9 → 1.3.0

package/src/VirtualShell/shellParser.ts

@@ -1,4 +1,10 @@
-import type { Pipeline, PipelineCommand, Script, Statement, LogicalOp } from "../types/pipeline";
+import type {
+	Pipeline,
+	PipelineCommand,
+	Script,
+	Statement,
+	LogicalOp,
+} from "../types/pipeline";
 
 // ── Public API ───────────────────────────────────────────────────────────────
 
@@ -56,8 +62,9 @@ export function expandToken(
 	token = token.replace(/\$#/g, "0");
 
 	// ${VAR:-default} and ${VAR:+value}
-	token = token.replace(/\$\{([^}:]+):-([^}]*)\}/g, (_, name, def) =>
-		env[name] ?? def,
+	token = token.replace(
+		/\$\{([^}:]+):-([^}]*)\}/g,
+		(_, name, def) => env[name] ?? def,
 	);
 	token = token.replace(/\$\{([^}:]+):\+([^}]*)\}/g, (_, name, val) =>
 		env[name] ? val : "",
@@ -67,8 +74,9 @@ export function expandToken(
 	token = token.replace(/\$\{([^}]+)\}/g, (_, name) => env[name] ?? "");
 
 	// $VAR (greedy: match longest valid identifier)
-	token = token.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) =>
-		env[name] ?? "",
+	token = token.replace(
+		/\$([A-Za-z_][A-Za-z0-9_]*)/g,
+		(_, name) => env[name] ?? "",
 	);
 
 	return token;
@@ -120,7 +128,10 @@ function parseStatements(input: string): Statement[] {
 	return statements;
 }
 
-interface Segment { text: string; op?: LogicalOp }
+interface Segment {
+	text: string;
+	op?: LogicalOp;
+}
 
 function splitByLogicalOps(input: string): Segment[] {
 	const segments: Segment[] = [];
@@ -139,19 +150,61 @@ function splitByLogicalOps(input: string): Segment[] {
 		const ch = input[i]!;
 		const ch2 = input.slice(i, i + 2);
 
-		if ((ch === '"' || ch === "'") && !inQ) { inQ = true; qChar = ch; current += ch; i++; continue; }
-		if (inQ && ch === qChar) { inQ = false; current += ch; i++; continue; }
-		if (inQ) { current += ch; i++; continue; }
+		if ((ch === '"' || ch === "'") && !inQ) {
+			inQ = true;
+			qChar = ch;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (inQ && ch === qChar) {
+			inQ = false;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			i++;
+			continue;
+		}
 
-		if (ch === "(") { depth++; current += ch; i++; continue; }
-		if (ch === ")") { depth--; current += ch; i++; continue; }
-		if (depth > 0) { current += ch; i++; continue; }
+		if (ch === "(") {
+			depth++;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (ch === ")") {
+			depth--;
+			current += ch;
+			i++;
+			continue;
+		}
+		if (depth > 0) {
+			current += ch;
+			i++;
+			continue;
+		}
 
-		if (ch2 === "&&") { flush("&&"); i += 2; continue; }
-		if (ch2 === "||") { flush("||"); i += 2; continue; }
-		if (ch === ";") { flush(";"); i++; continue; }
+		if (ch2 === "&&") {
+			flush("&&");
+			i += 2;
+			continue;
+		}
+		if (ch2 === "||") {
+			flush("||");
+			i += 2;
+			continue;
+		}
+		if (ch === ";") {
+			flush(";");
+			i++;
+			continue;
+		}
 
-		current += ch; i++;
+		current += ch;
+		i++;
 	}
 	flush();
 	return segments;
@@ -170,13 +223,26 @@ function splitByPipe(input: string): string[] {
 
 	for (let i = 0; i < input.length; i++) {
 		const ch = input[i]!;
-		if ((ch === '"' || ch === "'") && !inQ) { inQ = true; qChar = ch; current += ch; continue; }
-		if (inQ && ch === qChar) { inQ = false; current += ch; continue; }
-		if (inQ) { current += ch; continue; }
+		if ((ch === '"' || ch === "'") && !inQ) {
+			inQ = true;
+			qChar = ch;
+			current += ch;
+			continue;
+		}
+		if (inQ && ch === qChar) {
+			inQ = false;
+			current += ch;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			continue;
+		}
 
 		// || was already consumed at statement level, bare | is pipe
 		if (ch === "|" && input[i + 1] !== "|") {
-			if (!current.trim()) throw new Error("Syntax error near unexpected token '|'");
+			if (!current.trim())
+				throw new Error("Syntax error near unexpected token '|'");
 			tokens.push(current.trim());
 			current = "";
 		} else {
@@ -185,7 +251,8 @@ function splitByPipe(input: string): string[] {
 	}
 
 	const tail = current.trim();
-	if (!tail && tokens.length > 0) throw new Error("Syntax error near unexpected token '|'");
+	if (!tail && tokens.length > 0)
+		throw new Error("Syntax error near unexpected token '|'");
 	if (tail) tokens.push(tail);
 	return tokens;
 }
@@ -204,19 +271,27 @@ function parseCommandWithRedirections(token: string): PipelineCommand {
 		const part = parts[i]!;
 		if (part === "<") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after <");
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after <");
 			inputFile = parts[i];
 			i++;
 		} else if (part === ">>") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after >>");
-			outputFile = parts[i]; appendOutput = true; i++;
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after >>");
+			outputFile = parts[i];
+			appendOutput = true;
+			i++;
 		} else if (part === ">") {
 			i++;
-			if (i >= parts.length) throw new Error("Syntax error: expected filename after >");
-			outputFile = parts[i]; appendOutput = false; i++;
+			if (i >= parts.length)
+				throw new Error("Syntax error: expected filename after >");
+			outputFile = parts[i];
+			appendOutput = false;
+			i++;
 		} else {
-			cmdParts.push(part); i++;
+			cmdParts.push(part);
+			i++;
 		}
 	}
 
@@ -236,26 +311,49 @@ function tokenizeCommand(input: string): string[] {
 		const next = input[i + 1];
 
 		if ((ch === '"' || ch === "'") && !inQ) {
-			inQ = true; qChar = ch; i++; continue;
+			inQ = true;
+			qChar = ch;
+			i++;
+			continue;
 		}
 		if (inQ && ch === qChar) {
-			inQ = false; qChar = ""; i++; continue;
+			inQ = false;
+			qChar = "";
+			i++;
+			continue;
+		}
+		if (inQ) {
+			current += ch;
+			i++;
+			continue;
 		}
-		if (inQ) { current += ch; i++; continue; }
 
 		if (ch === " ") {
-			if (current) { tokens.push(current); current = ""; }
-			i++; continue;
+			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++; }
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			if (ch === ">" && next === ">") {
+				tokens.push(">>");
+				i += 2;
+			} else {
+				tokens.push(ch);
+				i++;
+			}
 			continue;
 		}
 
-		current += ch; i++;
+		current += ch;
+		i++;
 	}
 	if (current) tokens.push(current);
 	return tokens;

package/src/VirtualUserManager/index.ts

@@ -683,7 +683,10 @@ export class VirtualUserManager extends EventEmitter {
 			throw new Error("invalid password");
 		}
 	}
-	private readonly authorizedKeys = new Map<string, Array<{ algo: string; data: Buffer }>>();
+	private readonly authorizedKeys = new Map<
+		string,
+		Array<{ algo: string; data: Buffer }>
+	>();
 
 	/**
 	 * Adds an SSH public key for a user, enabling public-key authentication.
@@ -716,7 +719,9 @@ export class VirtualUserManager extends EventEmitter {
 	 *
 	 * @param username Target user.
 	 */
-	public getAuthorizedKeys(username: string): Array<{ algo: string; data: Buffer }> {
+	public getAuthorizedKeys(
+		username: string,
+	): Array<{ algo: string; data: Buffer }> {
 		return this.authorizedKeys.get(username) ?? [];
 	}
 }

package/src/commands/adduser.ts

@@ -1,5 +1,11 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Add a new user to the virtual user database.
+ * @category users
+ * @params ["<username> <password>"]
+ * @returns ShellModule
+ */
 export const adduserCommand: ShellModule = {
 	name: "adduser",
 	description: "Add a new user",

package/src/commands/alias.ts

@@ -1,6 +1,10 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
-
+/**
+ * Manage shell aliases (list / set / remove).
+ * @category shell
+ * @params ["[name[=value] ...]"]
+ */
 export const aliasCommand: ShellModule = {
 	name: "alias",
 	description: "Define or display aliases",

package/src/commands/apt.ts

@@ -1,16 +1,22 @@
 import type { ShellModule } from "../types/commands";
-import { ifFlag, } from "./command-helpers";
+import { ifFlag } from "./command-helpers";
 import { getPackageManager } from "./helpers";
 
+/**
+ * APT package manager front-end (simulated).
+ * @category package
+ * @params ["<install|remove|update|upgrade|search|show|list> [pkg...]"]
+ */
 export const aptCommand: ShellModule = {
 	name: "apt",
 	aliases: ["apt-get"],
 	description: "Package manager",
-	category: "system",
+	category: "package",
 	params: ["<install|remove|update|upgrade|search|show|list> [pkg...]"],
 	run: ({ args, shell, authUser }) => {
 		const pm = getPackageManager(shell);
-		if (!pm) return { stderr: "apt: package manager not initialised", exitCode: 1 };
+		if (!pm)
+			return { stderr: "apt: package manager not initialised", exitCode: 1 };
 
 		const sub = args[0]?.toLowerCase();
 		const rest = args.slice(1);
@@ -23,7 +29,8 @@ export const aptCommand: ShellModule = {
 		const restricted = ["install", "remove", "purge", "upgrade", "update"];
 		if (restricted.includes(sub ?? "") && authUser !== "root") {
 			return {
-				stderr: "E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock, are you root?",
+				stderr:
+					"E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock, are you root?",
 				exitCode: 100,
 			};
 		}
@@ -85,7 +92,8 @@ export const aptCommand: ShellModule = {
 						exitCode: 0,
 					};
 				const lines = results.map(
-					(p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64\n  ${p.shortDesc ?? p.description}`,
+					(p) =>
+						`${p.name}/${p.section ?? "misc"} ${p.version} amd64\n  ${p.shortDesc ?? p.description}`,
 				);
 				return {
 					stdout: `Sorting... Done\nFull Text Search... Done\n${lines.join("\n")}`,
@@ -95,10 +103,14 @@ export const aptCommand: ShellModule = {
 
 			case "show": {
 				const name = pkgs[0];
-				if (!name) return { stderr: "apt: show requires a package name", exitCode: 1 };
+				if (!name)
+					return { stderr: "apt: show requires a package name", exitCode: 1 };
 				const info = pm.show(name);
 				if (!info)
-					return { stderr: `N: Unable to locate package ${name}`, exitCode: 100 };
+					return {
+						stderr: `N: Unable to locate package ${name}`,
+						exitCode: 100,
+					};
 				return { stdout: info, exitCode: 0 };
 			}
 
@@ -107,11 +119,18 @@ export const aptCommand: ShellModule = {
 				if (installedFlag) {
 					const pkgList = pm.listInstalled();
 					if (pkgList.length === 0)
-						return { stdout: "Listing... Done\n(no packages installed)", exitCode: 0 };
+						return {
+							stdout: "Listing... Done\n(no packages installed)",
+							exitCode: 0,
+						};
 					const lines = pkgList.map(
-						(p) => `${p.name}/${p.section} ${p.version} ${p.architecture} [installed]`,
+						(p) =>
+							`${p.name}/${p.section} ${p.version} ${p.architecture} [installed]`,
 					);
-					return { stdout: `Listing... Done\n${lines.join("\n")}`, exitCode: 0 };
+					return {
+						stdout: `Listing... Done\n${lines.join("\n")}`,
+						exitCode: 0,
+					};
 				}
 				// all available
 				const all = pm.listAvailable();
@@ -146,11 +165,15 @@ export const aptCommand: ShellModule = {
 export const aptCacheCommand: ShellModule = {
 	name: "apt-cache",
 	description: "Query the package cache",
-	category: "system",
+	category: "package",
 	params: ["<search|show|policy> [pkg]"],
 	run: ({ args, shell }) => {
 		const pm = getPackageManager(shell);
-		if (!pm) return { stderr: "apt-cache: package manager not initialised", exitCode: 1 };
+		if (!pm)
+			return {
+				stderr: "apt-cache: package manager not initialised",
+				exitCode: 1,
+			};
 
 		const sub = args[0]?.toLowerCase();
 		const pkgName = args[1];
@@ -160,9 +183,10 @@ export const aptCacheCommand: ShellModule = {
 				if (!pkgName) return { stderr: "Need a search term", exitCode: 1 };
 				const results = pm.search(pkgName);
 				return {
-					stdout: results
-						.map((p) => `${p.name} - ${p.shortDesc ?? p.description}`)
-						.join("\n") || "(no results)",
+					stdout:
+						results
+							.map((p) => `${p.name} - ${p.shortDesc ?? p.description}`)
+							.join("\n") || "(no results)",
 					exitCode: 0,
 				};
 			}
@@ -177,7 +201,10 @@ export const aptCacheCommand: ShellModule = {
 				if (!pkgName) return { stderr: "Need a package name", exitCode: 1 };
 				const def = pm.findInRegistry(pkgName);
 				if (!def)
-					return { stderr: `N: Unable to locate package ${pkgName}`, exitCode: 100 };
+					return {
+						stderr: `N: Unable to locate package ${pkgName}`,
+						exitCode: 100,
+					};
 				const inst = pm.isInstalled(pkgName);
 				return {
 					stdout: [
@@ -192,7 +219,10 @@ export const aptCacheCommand: ShellModule = {
 				};
 			}
 			default:
-				return { stderr: `apt-cache: unknown command '${sub ?? ""}'`, exitCode: 1 };
+				return {
+					stderr: `apt-cache: unknown command '${sub ?? ""}'`,
+					exitCode: 1,
+				};
 		}
 	},
 };

package/src/commands/awk.ts

@@ -1,6 +1,17 @@
 import type { ShellModule } from "../types/commands";
 import { getFlag } from "./command-helpers";
 
+/**
+ * Minimal `awk`-like pattern scanner (supports simple print patterns).
+ * @category text
+ * @params ["[-F <sep>] '<program>' [file]"]
+ *
+ * Supported program patterns:
+ * - `print $N` (e.g. `print $1`, `print $2, $3`, `print $0`)
+ * - `{print $N}` (e.g. `{print $1}`, `{print $2, $3}`, `{print $0}`)
+ *
+ * The field separator can be set with `-F` (default is space, which splits on any whitespace).
+ */
 export const awkCommand: ShellModule = {
 	name: "awk",
 	description: "Pattern scanning and processing language (minimal)",
@@ -13,17 +24,20 @@ export const awkCommand: ShellModule = {
 
 		// Only support print $N and {print $N} patterns
 		const printMatch = prog.match(/^\{?\s*print\s+([^}]+)\s*\}?$/);
-		if (!printMatch) return { stderr: `awk: unsupported program: ${prog}`, exitCode: 1 };
+		if (!printMatch)
+			return { stderr: `awk: unsupported program: ${prog}`, exitCode: 1 };
 
 		const fields = printMatch[1]!.split(/\s*,\s*/).map((f) => f.trim());
 		const lines = (stdin ?? "").split("\n").filter(Boolean);
 		const out = lines.map((line) => {
 			const parts = line.split(sep === " " ? /\s+/ : sep);
-			return fields.map((f) => {
-				if (f === "$0") return line;
-				const n = parseInt(f.replace("$", ""), 10);
-				return Number.isNaN(n) ? f.replace(/"/g, "") : (parts[n - 1] ?? "");
-			}).join(sep === " " ? "\t" : sep);
+			return fields
+				.map((f) => {
+					if (f === "$0") return line;
+					const n = parseInt(f.replace("$", ""), 10);
+					return Number.isNaN(n) ? f.replace(/"/g, "") : (parts[n - 1] ?? "");
+				})
+				.join(sep === " " ? "\t" : sep);
 		});
 		return { stdout: out.join("\n"), exitCode: 0 };
 	},

package/src/commands/base64.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Encode or decode base64 data.
+ * @category text
+ * @params ["[-d] [file]"]
+ */
 export const base64Command: ShellModule = {
 	name: "base64",
 	description: "Encode/decode base64",
@@ -10,8 +15,14 @@ export const base64Command: ShellModule = {
 		const decode = ifFlag(args, ["-d", "--decode"]);
 		const input = stdin ?? "";
 		if (decode) {
-			try { return { stdout: Buffer.from(input.trim(), "base64").toString("utf8"), exitCode: 0 }; }
-			catch { return { stderr: "base64: invalid input", exitCode: 1 }; }
+			try {
+				return {
+					stdout: Buffer.from(input.trim(), "base64").toString("utf8"),
+					exitCode: 0,
+				};
+			} catch {
+				return { stderr: "base64: invalid input", exitCode: 1 };
+			}
 		}
 		return { stdout: Buffer.from(input).toString("base64"), exitCode: 0 };
 	},

package/src/commands/cat.ts

@@ -2,13 +2,18 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolveReadablePath } from "./helpers";
 
+/**
+ * Concatenate and print files to stdout.
+ * @category files
+ * @params ["[-n] [-b] <file...>"]
+ */
 export const catCommand: ShellModule = {
 	name: "cat",
 	description: "Concatenate and print files",
 	category: "files",
 	params: ["[-n] [-b] <file...>"],
 	run: ({ authUser, shell, cwd, args, stdin }) => {
-		const numberAll    = ifFlag(args, ["-n", "--number"]);
+		const numberAll = ifFlag(args, ["-n", "--number"]);
 		const numberNonBlank = ifFlag(args, ["-b", "--number-nonblank"]);
 		const fileArgs = args.filter((a) => !a.startsWith("-"));
 
@@ -34,10 +39,13 @@ export const catCommand: ShellModule = {
 		}
 
 		let lineNum = 1;
-		const numbered = combined.split("\n").map((line) => {
-			if (numberNonBlank && line.trim() === "") return line;
-			return `${String(lineNum++).padStart(6)}\t${line}`;
-		}).join("\n");
+		const numbered = combined
+			.split("\n")
+			.map((line) => {
+				if (numberNonBlank && line.trim() === "") return line;
+				return `${String(lineNum++).padStart(6)}\t${line}`;
+			})
+			.join("\n");
 
 		return { stdout: numbered, exitCode: 0 };
 	},

package/src/commands/cd.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Change current working directory.
+ * @category navigation
+ * @params ["[path]"]
+ */
 export const cdCommand: ShellModule = {
 	name: "cd",
 	description: "Change directory",

package/src/commands/chmod.ts

@@ -37,6 +37,11 @@ function applySymbolicMode(existing: number, modeStr: string): number | null {
 	return mode;
 }
 
+/**
+ * Change file permissions (octal or symbolic).
+ * @category files
+ * @params ["<mode> <file>"]
+ */
 export const chmodCommand: ShellModule = {
 	name: "chmod",
 	description: "Change file permissions",

package/src/commands/cp.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Copy files or directories inside the virtual filesystem.
+ * @category files
+ * @params ["[-r] <source> <dest>"]
+ */
 export const cpCommand: ShellModule = {
 	name: "cp",
 	description: "Copy files or directories",