typescript-virtual-container 1.2.8 → 1.3.0

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

@@ -0,0 +1,64 @@
+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",
+	category: "shell",
+	params: ["[name[=value] ...]"],
+	run: ({ args, env }) => {
+		if (!env) return { exitCode: 0 };
+
+		// Aliases stored in env.vars under prefix __alias_
+		if (args.length === 0) {
+			const aliases = Object.entries(env.vars)
+				.filter(([k]) => k.startsWith("__alias_"))
+				.map(([k, v]) => `alias ${k.slice("__alias_".length)}='${v}'`);
+			return { stdout: aliases.join("\n") || "", exitCode: 0 };
+		}
+
+		const lines: string[] = [];
+		for (const arg of args) {
+			const eq = arg.indexOf("=");
+			if (eq === -1) {
+				// Display single alias
+				const val = env.vars[`__alias_${arg}`];
+				if (val) lines.push(`alias ${arg}='${val}'`);
+				else return { stderr: `alias: ${arg}: not found`, exitCode: 1 };
+			} else {
+				// Set alias
+				const name = arg.slice(0, eq);
+				const val = arg.slice(eq + 1).replace(/^['"]|['"]$/g, "");
+				env.vars[`__alias_${name}`] = val;
+			}
+		}
+
+		return { stdout: lines.join("\n") || undefined, exitCode: 0 };
+	},
+};
+
+export const unaliasCommand: ShellModule = {
+	name: "unalias",
+	description: "Remove alias definitions",
+	category: "shell",
+	params: ["<name...> | -a"],
+	run: ({ args, env }) => {
+		if (!env) return { exitCode: 0 };
+
+		if (ifFlag(args, ["-a"])) {
+			for (const k of Object.keys(env.vars)) {
+				if (k.startsWith("__alias_")) delete env.vars[k];
+			}
+			return { exitCode: 0 };
+		}
+
+		for (const name of args) {
+			delete env.vars[`__alias_${name}`];
+		}
+		return { exitCode: 0 };
+	},
+};

package/src/commands/apt.ts

@@ -0,0 +1,228 @@
+import type { ShellModule } from "../types/commands";
+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: "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 };
+
+		const sub = args[0]?.toLowerCase();
+		const rest = args.slice(1);
+
+		const quiet = ifFlag(rest, ["-q", "--quiet", "-qq"]);
+		const purge = ifFlag(rest, ["--purge"]);
+		const pkgs = rest.filter((a) => !a.startsWith("-"));
+
+		// Non-root check
+		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?",
+				exitCode: 100,
+			};
+		}
+
+		switch (sub) {
+			case "install": {
+				if (pkgs.length === 0)
+					return { stderr: "apt: no packages specified", exitCode: 1 };
+				const { output, exitCode } = pm.install(pkgs, { quiet });
+				return { stdout: output || undefined, exitCode };
+			}
+
+			case "remove":
+			case "purge": {
+				if (pkgs.length === 0)
+					return { stderr: "apt: no packages specified", exitCode: 1 };
+				const { output, exitCode } = pm.remove(pkgs, {
+					purge: sub === "purge" || purge,
+					quiet,
+				});
+				return { stdout: output || undefined, exitCode };
+			}
+
+			case "update": {
+				return {
+					stdout: [
+						"Hit:1 fortune://packages.fortune.local aurora InRelease",
+						"Hit:2 fortune://security.fortune.local aurora-security InRelease",
+						"Reading package lists... Done",
+						"Building dependency tree... Done",
+						"Reading state information... Done",
+						`All packages are up to date.`,
+					].join("\n"),
+					exitCode: 0,
+				};
+			}
+
+			case "upgrade": {
+				return {
+					stdout: [
+						"Reading package lists... Done",
+						"Building dependency tree... Done",
+						"Reading state information... Done",
+						"Calculating upgrade... Done",
+						"0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.",
+					].join("\n"),
+					exitCode: 0,
+				};
+			}
+
+			case "search": {
+				const term = pkgs[0];
+				if (!term)
+					return { stderr: "apt: search requires a term", exitCode: 1 };
+				const results = pm.search(term);
+				if (results.length === 0)
+					return {
+						stdout: `Sorting... Done\nFull Text Search... Done\n(no results)`,
+						exitCode: 0,
+					};
+				const lines = results.map(
+					(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")}`,
+					exitCode: 0,
+				};
+			}
+
+			case "show": {
+				const name = pkgs[0];
+				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 { stdout: info, exitCode: 0 };
+			}
+
+			case "list": {
+				const installedFlag = ifFlag(rest, ["--installed"]);
+				if (installedFlag) {
+					const pkgList = pm.listInstalled();
+					if (pkgList.length === 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]`,
+					);
+					return {
+						stdout: `Listing... Done\n${lines.join("\n")}`,
+						exitCode: 0,
+					};
+				}
+				// all available
+				const all = pm.listAvailable();
+				const lines = all.map(
+					(p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64`,
+				);
+				return { stdout: `Listing... Done\n${lines.join("\n")}`, exitCode: 0 };
+			}
+
+			default: {
+				return {
+					stdout: [
+						"Usage: apt [options] command",
+						"",
+						"Commands:",
+						"  install <pkg...>   Install packages",
+						"  remove <pkg...>    Remove packages",
+						"  purge <pkg...>     Remove packages and config files",
+						"  update             Refresh package index",
+						"  upgrade            Upgrade all packages",
+						"  search <term>      Search in package descriptions",
+						"  show <pkg>         Show package details",
+						"  list [--installed] List packages",
+					].join("\n"),
+					exitCode: 0,
+				};
+			}
+		}
+	},
+};
+
+export const aptCacheCommand: ShellModule = {
+	name: "apt-cache",
+	description: "Query the package cache",
+	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,
+			};
+
+		const sub = args[0]?.toLowerCase();
+		const pkgName = args[1];
+
+		switch (sub) {
+			case "search": {
+				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)",
+					exitCode: 0,
+				};
+			}
+			case "show": {
+				if (!pkgName) return { stderr: "Need a package name", exitCode: 1 };
+				const info = pm.show(pkgName);
+				return info
+					? { stdout: info, exitCode: 0 }
+					: { stderr: `N: Unable to locate package ${pkgName}`, exitCode: 100 };
+			}
+			case "policy": {
+				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,
+					};
+				const inst = pm.isInstalled(pkgName);
+				return {
+					stdout: [
+						`${pkgName}:`,
+						`  Installed: ${inst ? def.version : "(none)"}`,
+						`  Candidate: ${def.version}`,
+						`  Version table:`,
+						`     ${def.version} 500`,
+						`        500 fortune://packages.fortune.local aurora/main amd64 Packages`,
+					].join("\n"),
+					exitCode: 0,
+				};
+			}
+			default:
+				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

@@ -1,20 +1,52 @@
 import type { ShellModule } from "../types/commands";
-import { getArg } from "./command-helpers";
+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: ["<file>"],
-	run: ({ authUser, shell, cwd, args }) => {
-		const fileArg = getArg(args, 0);
-		if (!fileArg) {
+	params: ["[-n] [-b] <file...>"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const numberAll = ifFlag(args, ["-n", "--number"]);
+		const numberNonBlank = ifFlag(args, ["-b", "--number-nonblank"]);
+		const fileArgs = args.filter((a) => !a.startsWith("-"));
+
+		if (fileArgs.length === 0 && stdin !== undefined) {
+			return { stdout: stdin, exitCode: 0 };
+		}
+
+		if (fileArgs.length === 0) {
 			return { stderr: "cat: missing file operand", exitCode: 1 };
 		}
 
-		const target = resolveReadablePath(shell.vfs, cwd, fileArg);
-		assertPathAccess(authUser, target, "cat");
-		return { stdout: shell.vfs.readFile(target), exitCode: 0 };
+		const parts: string[] = [];
+		for (const fileArg of fileArgs) {
+			const target = resolveReadablePath(shell.vfs, cwd, fileArg);
+			assertPathAccess(authUser, target, "cat");
+			parts.push(shell.vfs.readFile(target));
+		}
+
+		const combined = parts.join("");
+
+		if (!numberAll && !numberNonBlank) {
+			return { stdout: combined, exitCode: 0 };
+		}
+
+		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");
+
+		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

@@ -1,6 +1,47 @@
 import type { ShellModule } from "../types/commands";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Parse a symbolic chmod mode string (e.g. "+x", "u+x", "go-w", "a+rx")
+ * and apply it to the existing mode bits.
+ * Returns null if the string is not a valid symbolic mode.
+ */
+function applySymbolicMode(existing: number, modeStr: string): number | null {
+	const pattern = /^([ugoa]*)([+\-=])([rwx]*)$/;
+	const parts = modeStr.split(",");
+	let mode = existing;
+	for (const part of parts) {
+		const m = part.trim().match(pattern);
+		if (!m) return null;
+		const [, who = "a", op, perms = ""] = m;
+		const targets = who === "" || who === "a" ? ["u", "g", "o"] : who.split("");
+		const bits: Record<string, Record<string, number>> = {
+			u: { r: 0o400, w: 0o200, x: 0o100 },
+			g: { r: 0o040, w: 0o020, x: 0o010 },
+			o: { r: 0o004, w: 0o002, x: 0o001 },
+		};
+		for (const t of targets) {
+			for (const p of perms.split("")) {
+				const bit = bits[t]?.[p];
+				if (bit === undefined) continue;
+				if (op === "+") mode |= bit;
+				else if (op === "-") mode &= ~bit;
+				else if (op === "=") {
+					// clear all bits for this target, then set requested
+					const mask = Object.values(bits[t] ?? {}).reduce((a, b) => a | b, 0);
+					mode = (mode & ~mask) | bit;
+				}
+			}
+		}
+	}
+	return mode;
+}
+
+/**
+ * Change file permissions (octal or symbolic).
+ * @category files
+ * @params ["<mode> <file>"]
+ */
 export const chmodCommand: ShellModule = {
 	name: "chmod",
 	description: "Change file permissions",
@@ -21,9 +62,18 @@ export const chmodCommand: ShellModule = {
 					exitCode: 1,
 				};
 			}
-			const mode = parseInt(modeArg, 8);
-			if (Number.isNaN(mode)) {
-				return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+			let mode: number;
+			const octal = parseInt(modeArg, 8);
+			if (!Number.isNaN(octal) && /^[0-7]+$/.test(modeArg)) {
+				mode = octal;
+			} else {
+				// symbolic mode
+				const existing = shell.vfs.stat(filePath).mode;
+				const result = applySymbolicMode(existing, modeArg);
+				if (result === null) {
+					return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+				}
+				mode = result;
 			}
 			shell.vfs.chmod(filePath, mode);
 			return { exitCode: 0 };

package/src/commands/command-helpers.ts

@@ -80,6 +80,23 @@ function collectPositionals(
 	return positionals;
 }
 
+/**
+ * Returns `true` when any of the given flags appear in `args`.
+ *
+ * Matches both standalone tokens (`-s`, `--silent`) and inline forms
+ * (`--output=file`). Useful for simple boolean flag checks inside command
+ * `run` handlers.
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns `true` if at least one flag is present, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * ifFlag(args, "-r")              // single flag
+ * ifFlag(args, ["-r", "--recursive"]) // aliases
+ * ```
+ */
 export function ifFlag(args: string[], flags: string | string[]): boolean {
 	const allFlags = toFlagList(flags);
 
@@ -94,6 +111,25 @@ export function ifFlag(args: string[], flags: string | string[]): boolean {
 	return false;
 }
 
+/**
+ * Returns the value associated with a flag, or `true` if the flag is present
+ * but has no associated value, or `undefined` if the flag is absent.
+ *
+ * Handles three forms:
+ * - `--output file`   → returns `"file"` (next token)
+ * - `--output=file`   → returns `"file"` (inline `=` form)
+ * - `--verbose`       → returns `true` (flag with no value)
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns The flag value string, `true` when valueless, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const output = getFlag(args, ["-o", "--output"]);
+ * if (typeof output === "string") { /* use path *\/ }
+ * ```
+ */
 export function getFlag(
 	args: string[],
 	flags: string | string[],
@@ -125,6 +161,26 @@ export function getFlag(
 	return undefined;
 }
 
+/**
+ * Returns the positional argument at the given zero-based index, skipping
+ * known flags and their values.
+ *
+ * Flags declared in `options.flags` are treated as boolean and skipped.
+ * Flags declared in `options.flagsWithValue` consume the next token too.
+ * Tokens after `--` are always treated as positionals.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param index   Zero-based positional index to retrieve.
+ * @param options Optional flag declarations to skip during positional collection.
+ * @returns The positional value, or `undefined` if the index is out of range.
+ *
+ * @example
+ * ```ts
+ * // args = ["-r", "src", "dest"]
+ * getArg(args, 0, { flags: ["-r"] }) // "src"
+ * getArg(args, 1, { flags: ["-r"] }) // "dest"
+ * ```
+ */
 export function getArg(
 	args: string[],
 	index: number,
@@ -135,10 +191,28 @@ export function getArg(
 }
 
 /**
- * Parse arguments into flags, flags with values, and positionals.
- * @param args - Array of arguments to parse.
- * @param options - Parsing options for flags and flags with values.
- * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ * Parses an argument array into structured flags, flag values, and positionals.
+ *
+ * - `options.flags` — boolean flags (e.g. `["-r", "--recursive"]`); collected
+ *   into a `Set<string>` and not treated as positionals.
+ * - `options.flagsWithValue` — flags that consume the next token or an inline
+ *   `=value`; collected into a `Map<string, string>`.
+ * - All remaining tokens are positionals.
+ * - Tokens after `--` are always positionals, regardless of `-` prefix.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param options Flag declaration lists.
+ * @returns `{ flags, flagsWithValues, positionals }`.
+ *
+ * @example
+ * ```ts
+ * const { flags, flagsWithValues, positionals } = parseArgs(args, {
+ *   flags:          ["-r", "--recursive"],
+ *   flagsWithValue: ["-o", "--output"],
+ * });
+ * const recursive = flags.has("-r");
+ * const output    = flagsWithValues.get("-o");
+ * ```
  */
 export function parseArgs(
 	args: string[],

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