typescript-virtual-container 1.2.7 → 1.2.9

package/src/commands/chmod.ts

@@ -1,6 +1,42 @@
 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;
+}
+
 export const chmodCommand: ShellModule = {
 	name: "chmod",
 	description: "Change file permissions",
@@ -21,9 +57,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/curl.ts

@@ -1,61 +1,102 @@
 import type { ShellModule } from "../types/commands";
-import { parseArgs } from "./command-helpers";
-import {
-	assertPathAccess,
-	normalizeTerminalOutput,
-	resolvePath,
-	runHostCommand,
-} from "./helpers";
+import { ifFlag, parseArgs } from "./command-helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
 
 export const curlCommand: ShellModule = {
 	name: "curl",
-	description: "HTTP client",
+	description: "Transfer data from or to a server (pure fetch)",
 	category: "network",
-	params: ["[-o file] <url>"],
+	params: ["[options] <url>"],
 	run: async ({ authUser, cwd, args, shell }) => {
 		const { flagsWithValues, positionals } = parseArgs(args, {
-			flagsWithValue: ["-o", "--output"],
+			flagsWithValue: ["-o", "--output", "-X", "--request", "-d", "--data", "-H", "--header", "-u", "--user"],
 		});
-		const outputPath =
-			flagsWithValues.get("-o") || flagsWithValues.get("--output") || null;
+
+		if (ifFlag(args, ["--help", "-h"])) {
+			return {
+				stdout: [
+					"Usage: curl [options] <url>",
+					"  -o, --output <file>    Write to file",
+					"  -X, --request <method> HTTP method",
+					"  -d, --data <data>      POST data",
+					"  -H, --header <hdr>     Extra header",
+					"  -s, --silent           Silent mode",
+					"  -I, --head             Fetch headers only",
+					"  -L, --location         Follow redirects",
+					"  -v, --verbose          Verbose",
+				].join("\n"),
+				exitCode: 0,
+			};
+		}
+
 		const url = positionals[0];
+		if (!url) return { stderr: "curl: no URL specified", exitCode: 1 };
 
-		if (!url) {
-			return { stderr: "curl: missing URL", exitCode: 1 };
+		const outputPath = flagsWithValues.get("-o") ?? flagsWithValues.get("--output") ?? null;
+		const method = (flagsWithValues.get("-X") ?? flagsWithValues.get("--request") ?? "GET").toUpperCase();
+		const postData = flagsWithValues.get("-d") ?? flagsWithValues.get("--data") ?? null;
+		const headerRaw = flagsWithValues.get("-H") ?? flagsWithValues.get("--header") ?? null;
+		const silent = ifFlag(args, ["-s", "--silent"]);
+		const headOnly = ifFlag(args, ["-I", "--head"]);
+		const followRedirects = ifFlag(args, ["-L", "--location"]);
+		const verbose = ifFlag(args, ["-v", "--verbose"]);
+
+		const extraHeaders: Record<string, string> = { "User-Agent": "curl/7.88.1" };
+		if (headerRaw) {
+			const idx = headerRaw.indexOf(":");
+			if (idx !== -1) extraHeaders[headerRaw.slice(0, idx).trim()] = headerRaw.slice(idx + 1).trim();
 		}
 
-		const passthroughArgs = outputPath
-			? [...positionals, "-o", "-"]
-			: positionals;
-		const result = await runHostCommand("curl", passthroughArgs);
+		const finalMethod = postData && method === "GET" ? "POST" : method;
+		const fetchOpts: RequestInit = {
+			method: finalMethod,
+			headers: extraHeaders,
+			redirect: followRedirects ? "follow" : "manual",
+		};
+		if (postData) {
+			extraHeaders["Content-Type"] ??= "application/x-www-form-urlencoded";
+			fetchOpts.body = postData;
+		}
 
-		if (result.exitCode !== 0) {
-			return {
-				stderr: normalizeTerminalOutput(
-					result.stderr || `curl: exited with code ${result.exitCode}`,
-				),
-				exitCode: result.exitCode,
-			};
+		const stderrLines: string[] = [];
+		if (verbose) {
+			stderrLines.push(`* Trying ${url}...`, `* Connected`);
+			stderrLines.push(`> ${finalMethod} / HTTP/1.1`, `> Host: ${new URL(url).host}`);
 		}
 
+		let response: Response;
+		try {
+			response = await fetch(url, fetchOpts);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return { stderr: `curl: (6) Could not resolve host: ${msg}`, exitCode: 6 };
+		}
+
+		if (verbose) {
+			stderrLines.push(`< HTTP/1.1 ${response.status} ${response.statusText}`);
+		}
+
+		if (headOnly) {
+			const lines = [`HTTP/1.1 ${response.status} ${response.statusText}`];
+			for (const [k, v] of response.headers.entries()) lines.push(`${k}: ${v}`);
+			return { stdout: `${lines.join("\r\n")}\r\n`, exitCode: 0 };
+		}
+
+		let body: string;
+		try { body = await response.text(); } catch { return { stderr: "curl: failed to read response body", exitCode: 1 }; }
+
 		if (outputPath) {
 			const target = resolvePath(cwd, outputPath);
 			assertPathAccess(authUser, target, "curl");
-			shell.writeFileAsUser(authUser, target, result.stdout);
-			return {
-				stderr: result.stderr
-					? normalizeTerminalOutput(result.stderr)
-					: undefined,
-				exitCode: 0,
-			};
+			shell.writeFileAsUser(authUser, target, body);
+			if (!silent) stderrLines.push(`  % Total    % Received\n100 ${body.length}  100 ${body.length}`);
+			return { stderr: stderrLines.join("\n") || undefined, exitCode: response.ok ? 0 : 22 };
 		}
 
 		return {
-			stdout: result.stdout,
-			stderr: result.stderr
-				? normalizeTerminalOutput(result.stderr)
-				: undefined,
-			exitCode: 0,
+			stdout: body,
+			stderr: stderrLines.length > 0 ? stderrLines.join("\n") : undefined,
+			exitCode: response.ok ? 0 : 22,
 		};
 	},
 };

package/src/commands/dpkg.ts

@@ -0,0 +1,158 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag, parseArgs } from "./command-helpers";
+import { getPackageManager } from "./helpers";
+
+export const dpkgCommand: ShellModule = {
+	name: "dpkg",
+	description: "Debian package manager low-level tool",
+	category: "system",
+	params: ["[-l] [-s pkg] [-L pkg] [-i pkg] [--remove pkg]"],
+	run: ({ args, authUser, shell }) => {
+		const pm = getPackageManager(shell);
+		if (!pm) return { stderr: "dpkg: package manager not initialised", exitCode: 1 };
+
+		const listFlag = ifFlag(args, ["-l", "--list"]);
+		const statusFlag = ifFlag(args, ["-s", "--status"]);
+		const listFilesFlag = ifFlag(args, ["-L", "--listfiles"]);
+		const removeFlag = ifFlag(args, ["-r", "--remove"]);
+		const purgeFlag = ifFlag(args, ["-P", "--purge"]);
+
+		const { positionals } = parseArgs(args, {
+			flags: ["-l", "--list", "-s", "--status", "-L", "--listfiles", "-r", "--remove", "-P", "--purge"],
+		});
+
+		if (listFlag) {
+			const pkgList = pm.listInstalled();
+			if (pkgList.length === 0) {
+				return {
+					stdout: [
+						"Desired=Unknown/Install/Remove/Purge/Hold",
+						"|Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend",
+						"|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)",
+						"||/ Name           Version         Architecture Description",
+						"+++-==============-===============-============-========================================",
+						"(no packages installed)",
+					].join("\n"),
+					exitCode: 0,
+				};
+			}
+
+			const header = [
+				"Desired=Unknown/Install/Remove/Purge/Hold",
+				"|Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend",
+				"|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)",
+				"||/ Name           Version         Architecture Description",
+				"+++-==============-===============-============-========================================",
+			];
+
+			const rows = pkgList.map((p) => {
+				const name = p.name.padEnd(14).slice(0, 14);
+				const ver = p.version.padEnd(15).slice(0, 15);
+				const arch = p.architecture.padEnd(12).slice(0, 12);
+				const desc = (p.description || "").slice(0, 40);
+				return `ii  ${name} ${ver} ${arch} ${desc}`;
+			});
+
+			return { stdout: [...header, ...rows].join("\n"), exitCode: 0 };
+		}
+
+		if (statusFlag) {
+			const pkgName = positionals[0];
+			if (!pkgName) return { stderr: "dpkg: -s needs a package name", exitCode: 1 };
+			const info = pm.show(pkgName);
+			if (!info)
+				return {
+					stderr: `dpkg-query: package '${pkgName}' is not installed and no information is available`,
+					exitCode: 1,
+				};
+			return { stdout: info, exitCode: 0 };
+		}
+
+		if (listFilesFlag) {
+			const pkgName = positionals[0];
+			if (!pkgName) return { stderr: "dpkg: -L needs a package name", exitCode: 1 };
+			const installed = pm.listInstalled().find((p) => p.name === pkgName);
+			if (!installed)
+				return {
+					stderr: `dpkg-query: package '${pkgName}' is not installed`,
+					exitCode: 1,
+				};
+			if (installed.files.length === 0)
+				return { stdout: "/.keep", exitCode: 0 };
+			return { stdout: installed.files.join("\n"), exitCode: 0 };
+		}
+
+		if (removeFlag || purgeFlag) {
+			if (authUser !== "root")
+				return {
+					stderr: "dpkg: error: requested operation requires superuser privilege",
+					exitCode: 2,
+				};
+			if (positionals.length === 0)
+				return { stderr: "dpkg: error: need an action option", exitCode: 2 };
+			const { output, exitCode } = pm.remove(positionals, { purge: purgeFlag });
+			return { stdout: output || undefined, exitCode };
+		}
+
+		// Default: show help
+		return {
+			stdout: [
+				"Usage: dpkg [<option>...] <command>",
+				"",
+				"Commands:",
+				"  -l, --list                  List packages matching given pattern",
+				"  -s, --status <pkg>...       Report status of specified package",
+				"  -L, --listfiles <pkg>...    List files owned by package",
+				"  -r, --remove <pkg>...       Remove <pkg> but leave its configuration",
+				"  -P, --purge <pkg>...        Remove <pkg> and its configuration",
+			].join("\n"),
+			exitCode: 0,
+		};
+	},
+};
+
+export const dpkgQueryCommand: ShellModule = {
+	name: "dpkg-query",
+	description: "Show information about installed packages",
+	category: "system",
+	params: ["-W [pkg] | -l [pattern]"],
+	run: ({ args, shell }) => {
+		const pm = getPackageManager(shell);
+		if (!pm) return { stderr: "dpkg-query: package manager not initialised", exitCode: 1 };
+
+		const listFlag = ifFlag(args, ["-l"]);
+		const showFlag = ifFlag(args, ["-W", "--show"]);
+		const { positionals } = parseArgs(args, {
+			flags: ["-l", "-W", "--show"],
+		});
+
+		if (listFlag || showFlag) {
+			const pkgList = pm.listInstalled();
+			const pattern = positionals[0];
+			const filtered = pattern
+				? pkgList.filter((p) => p.name.includes(pattern))
+				: pkgList;
+
+			if (showFlag) {
+				return {
+					stdout: filtered
+						.map((p) => `${p.name}\t${p.version}`)
+						.join("\n"),
+					exitCode: 0,
+				};
+			}
+
+			const rows = filtered.map((p) => {
+				const name = p.name.padEnd(14).slice(0, 14);
+				const ver = p.version.padEnd(15).slice(0, 15);
+				return `ii  ${name} ${ver} amd64 ${(p.description || "").slice(0, 40)}`;
+			});
+			return {
+				stdout: rows.join("\n") || "(no packages match)",
+				exitCode: 0,
+			};
+		}
+
+		return { stderr: "dpkg-query: need a flag (-l, -W)", exitCode: 1 };
+	},
+};

package/src/commands/echo.ts

@@ -1,28 +1,44 @@
 import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
-import { getAllEnvVars } from "./set";
 
-function expandEnvVars(input: string, env: Record<string, string>): string {
-	return input.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name: string) => {
-		return env[name] ?? "";
-	});
+/**
+ * Expand escape sequences for `echo -e`.
+ * Handles \n \t \r \\ \a \b \f \v and \0NNN (octal).
+ */
+function expandEscapes(text: string): string {
+	return text
+		.replace(/\\n/g, "\n")
+		.replace(/\\t/g, "\t")
+		.replace(/\\r/g, "\r")
+		.replace(/\\\\/g, "\\")
+		.replace(/\\a/g, "\x07")
+		.replace(/\\b/g, "\x08")
+		.replace(/\\f/g, "\x0C")
+		.replace(/\\v/g, "\x0B")
+		.replace(/\\0(\d{1,3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)));
 }
 
 export const echoCommand: ShellModule = {
 	name: "echo",
 	description: "Display text",
 	category: "shell",
-	params: ["[options] [text...]"],
-	run: ({ args, authUser, stdin }) => {
-		const { flags, positionals } = parseArgs(args, { flags: ["-n"] });
-		const newline = !flags.has("-n");
-		const rawText =
-			positionals.length > 0 ? positionals.join(" ") : (stdin ?? "");
-		const env = getAllEnvVars(authUser);
-		const text = expandEnvVars(rawText, env);
+	params: ["[-n] [-e] [text...]"],
+	run: ({ args, stdin, env }) => {
+		const { flags, positionals } = parseArgs(args, { flags: ["-n", "-e", "-E"] });
+		const noNewline = flags.has("-n");
+		const escapes  = flags.has("-e");
+
+		const rawText = positionals.length > 0 ? positionals.join(" ") : (stdin ?? "");
+
+		// Expand $VAR references using the session env (not the legacy global store)
+		const varsExpanded = rawText.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name: string) =>
+			env?.vars[name] ?? "",
+		);
+
+		const text = escapes ? expandEscapes(varsExpanded) : varsExpanded;
 
 		return {
-			stdout: newline ? text : text.trimEnd(),
+			stdout: noNewline ? text : `${text}\n`,
 			exitCode: 0,
 		};
 	},

package/src/commands/free.ts

@@ -0,0 +1,40 @@
+import * as os from "node:os";
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+
+export const freeCommand: ShellModule = {
+	name: "free",
+	description: "Display amount of free and used memory",
+	category: "system",
+	params: ["[-h] [-m] [-g]"],
+	run: ({ args }) => {
+		const human = ifFlag(args, ["-h", "--human"]);
+		const mb = ifFlag(args, ["-m"]);
+		const gb = ifFlag(args, ["-g"]);
+
+		const osTotalB = os.totalmem();
+		const osFreeB = os.freemem();
+		const usedB = osTotalB - osFreeB;
+		const sharedB = Math.floor(osTotalB * 0.02);
+		const buffersB = Math.floor(osTotalB * 0.05);
+		const availableB = Math.floor(osFreeB * 0.95);
+		const swapB = Math.floor(osTotalB * 0.5);
+
+		const fmt = (bytes: number): string => {
+			if (human) {
+				if (bytes >= 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+				if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+				return `${(bytes / 1024).toFixed(1)}K`;
+			}
+			if (gb) return String(Math.floor(bytes / (1024 * 1024 * 1024)));
+			if (mb) return String(Math.floor(bytes / (1024 * 1024)));
+			return String(Math.floor(bytes / 1024));
+		};
+
+		const header = `               total        used        free      shared  buff/cache   available`;
+		const memRow = `Mem:  ${fmt(osTotalB).padStart(12)} ${fmt(usedB).padStart(11)} ${fmt(osFreeB).padStart(11)} ${fmt(sharedB).padStart(11)} ${fmt(buffersB).padStart(11)} ${fmt(availableB).padStart(11)}`;
+		const swapRow = `Swap: ${fmt(swapB).padStart(12)} ${fmt(0).padStart(11)} ${fmt(swapB).padStart(11)}`;
+
+		return { stdout: [header, memRow, swapRow].join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/helpers.ts

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import * as path from "node:path";
 import type VirtualFileSystem from "../VirtualFileSystem";
+import type { VirtualPackageManager } from "../VirtualPackageManager";
+import type { VirtualShell } from "../VirtualShell";
 
 const PROTECTED_PREFIXES = ["/virtual-env-js/.auth"] as const;
 
@@ -220,3 +222,9 @@ export function joinListWithType(
 		})
 		.join("  ");
 }
+
+export function getPackageManager(
+	shell: VirtualShell,
+): VirtualPackageManager | undefined {
+	return shell.packageManager;
+}

package/src/commands/history.ts

@@ -0,0 +1,29 @@
+import type { ShellModule } from "../types/commands";
+
+export const historyCommand: ShellModule = {
+	name: "history",
+	description: "Display command history",
+	category: "shell",
+	params: ["[n]"],
+	run: ({ args, shell }) => {
+		// History is persisted in the VFS by the interactive shell
+		const histPath = "/virtual-env-js/.bash_history";
+		if (!shell.vfs.exists(histPath)) {
+			return { stdout: "", exitCode: 0 };
+		}
+
+		const raw = shell.vfs.readFile(histPath);
+		const lines = raw.split("\n").filter(Boolean);
+
+		const nArg = args[0];
+		const n = nArg ? parseInt(nArg, 10) : null;
+		const slice = n && !Number.isNaN(n) ? lines.slice(-n) : lines;
+
+		const offset = lines.length - slice.length + 1;
+		const numbered = slice.map((line, i) =>
+			`${String(offset + i).padStart(5)}  ${line}`
+		);
+
+		return { stdout: numbered.join("\n"), exitCode: 0 };
+	},
+};