typescript-virtual-container 1.2.9 → 1.3.0

package/src/commands/curl.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag, parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * HTTP client wrapper using `fetch()` semantics (virtual curl).
+ * @category network
+ * @params ["[options] <url>"]
+ */
 export const curlCommand: ShellModule = {
 	name: "curl",
 	description: "Transfer data from or to a server (pure fetch)",
@@ -9,7 +14,18 @@ export const curlCommand: ShellModule = {
 	params: ["[options] <url>"],
 	run: async ({ authUser, cwd, args, shell }) => {
 		const { flagsWithValues, positionals } = parseArgs(args, {
-			flagsWithValue: ["-o", "--output", "-X", "--request", "-d", "--data", "-H", "--header", "-u", "--user"],
+			flagsWithValue: [
+				"-o",
+				"--output",
+				"-X",
+				"--request",
+				"-d",
+				"--data",
+				"-H",
+				"--header",
+				"-u",
+				"--user",
+			],
 		});
 
 		if (ifFlag(args, ["--help", "-h"])) {
@@ -32,19 +48,31 @@ export const curlCommand: ShellModule = {
 		const url = positionals[0];
 		if (!url) return { stderr: "curl: no URL specified", 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 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" };
+		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();
+			if (idx !== -1)
+				extraHeaders[headerRaw.slice(0, idx).trim()] = headerRaw
+					.slice(idx + 1)
+					.trim();
 		}
 
 		const finalMethod = postData && method === "GET" ? "POST" : method;
@@ -61,7 +89,10 @@ export const curlCommand: ShellModule = {
 		const stderrLines: string[] = [];
 		if (verbose) {
 			stderrLines.push(`* Trying ${url}...`, `* Connected`);
-			stderrLines.push(`> ${finalMethod} / HTTP/1.1`, `> Host: ${new URL(url).host}`);
+			stderrLines.push(
+				`> ${finalMethod} / HTTP/1.1`,
+				`> Host: ${new URL(url).host}`,
+			);
 		}
 
 		let response: Response;
@@ -69,7 +100,10 @@ export const curlCommand: ShellModule = {
 			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 };
+			return {
+				stderr: `curl: (6) Could not resolve host: ${msg}`,
+				exitCode: 6,
+			};
 		}
 
 		if (verbose) {
@@ -83,14 +117,24 @@ export const curlCommand: ShellModule = {
 		}
 
 		let body: string;
-		try { body = await response.text(); } catch { return { stderr: "curl: failed to read response body", exitCode: 1 }; }
+		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, body);
-			if (!silent) stderrLines.push(`  % Total    % Received\n100 ${body.length}  100 ${body.length}`);
-			return { stderr: stderrLines.join("\n") || undefined, exitCode: response.ok ? 0 : 22 };
+			if (!silent)
+				stderrLines.push(
+					`  % Total    % Received\n100 ${body.length}  100 ${body.length}`,
+				);
+			return {
+				stderr: stderrLines.join("\n") || undefined,
+				exitCode: response.ok ? 0 : 22,
+			};
 		}
 
 		return {

package/src/commands/cut.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { getFlag } from "./command-helpers";
 
+/**
+ * Extract selected fields from each line of input.
+ * @category text
+ * @params ["-d <delim> -f <fields> [file]"]
+ */
 export const cutCommand: ShellModule = {
 	name: "cut",
 	description: "Remove sections from lines",
@@ -11,7 +16,9 @@ export const cutCommand: ShellModule = {
 		const fields = (getFlag(args, ["-f"]) as string | undefined) ?? "1";
 		const cols = fields.split(",").map((f) => {
 			const [a, b] = f.split("-").map(Number);
-			return b !== undefined ? { from: (a ?? 1) - 1, to: b - 1 } : { from: (a ?? 1) - 1, to: (a ?? 1) - 1 };
+			return b !== undefined
+				? { from: (a ?? 1) - 1, to: b - 1 }
+				: { from: (a ?? 1) - 1, to: (a ?? 1) - 1 };
 		});
 		const lines = (stdin ?? "").split("\n");
 		const out = lines.map((line) => {

package/src/commands/date.ts

@@ -1,5 +1,10 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Print the current date/time or a formatted representation.
+ * @category system
+ * @params ["[+format]"]
+ */
 export const dateCommand: ShellModule = {
 	name: "date",
 	description: "Print current date and time",
@@ -9,7 +14,8 @@ export const dateCommand: ShellModule = {
 		const now = new Date();
 		const fmt = args[0];
 		if (fmt?.startsWith("+")) {
-			const f = fmt.slice(1)
+			const f = fmt
+				.slice(1)
 				.replace("%Y", String(now.getFullYear()))
 				.replace("%m", String(now.getMonth() + 1).padStart(2, "0"))
 				.replace("%d", String(now.getDate()).padStart(2, "0"))

package/src/commands/declare.ts

@@ -0,0 +1,44 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+
+export const declareCommand: ShellModule = {
+	name: "declare",
+	aliases: ["local", "typeset"],
+	description: "Declare variables and give them attributes",
+	category: "shell",
+	params: ["[-i] [-r] [-x] [-a] [name[=value]...]"],
+	run: ({ args, env }) => {
+		if (!env) return { exitCode: 0 };
+
+		const integer = ifFlag(args, ["-i"]);
+		const _readonly = ifFlag(args, ["-r"]);
+		const _export_ = ifFlag(args, ["-x"]);
+		const printAll = args.filter((a) => !a.startsWith("-")).length === 0;
+
+		if (printAll) {
+			const lines = Object.entries(env.vars).map(
+				([k, v]) => `declare -- ${k}="${v}"`,
+			);
+			return { stdout: lines.join("\n"), exitCode: 0 };
+		}
+
+		const assignments = args.filter((a) => !a.startsWith("-"));
+		for (const token of assignments) {
+			const eq = token.indexOf("=");
+			if (eq === -1) {
+				// Just declare (no value)
+				if (!(token in env.vars)) env.vars[token] = "";
+			} else {
+				const name = token.slice(0, eq);
+				let val = token.slice(eq + 1);
+				if (integer) {
+					const n = parseInt(val, 10);
+					val = Number.isNaN(n) ? "0" : String(n);
+				}
+				env.vars[name] = val;
+			}
+		}
+
+		return { exitCode: 0 };
+	},
+};

package/src/commands/diff.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { resolvePath } from "./helpers";
 
+/**
+ * Compare files line-by-line and print differing lines.
+ * @category text
+ * @params ["<file1> <file2>"]
+ */
 export const diffCommand: ShellModule = {
 	name: "diff",
 	description: "Compare files line by line",
@@ -12,13 +17,22 @@ export const diffCommand: ShellModule = {
 		const p1 = resolvePath(cwd, f1);
 		const p2 = resolvePath(cwd, f2);
 		let a: string[], b: string[];
-		try { a = shell.vfs.readFile(p1).split("\n"); } catch { return { stderr: `diff: ${f1}: No such file or directory`, exitCode: 2 }; }
-		try { b = shell.vfs.readFile(p2).split("\n"); } catch { return { stderr: `diff: ${f2}: No such file or directory`, exitCode: 2 }; }
+		try {
+			a = shell.vfs.readFile(p1).split("\n");
+		} catch {
+			return { stderr: `diff: ${f1}: No such file or directory`, exitCode: 2 };
+		}
+		try {
+			b = shell.vfs.readFile(p2).split("\n");
+		} catch {
+			return { stderr: `diff: ${f2}: No such file or directory`, exitCode: 2 };
+		}
 
 		const out: string[] = [];
 		const max = Math.max(a.length, b.length);
 		for (let i = 0; i < max; i++) {
-			const la = a[i]; const lb = b[i];
+			const la = a[i];
+			const lb = b[i];
 			if (la !== lb) {
 				if (la !== undefined) out.push(`< ${la}`);
 				if (lb !== undefined) out.push(`> ${lb}`);

package/src/commands/dpkg.ts

@@ -2,14 +2,20 @@ import type { ShellModule } from "../types/commands";
 import { ifFlag, parseArgs } from "./command-helpers";
 import { getPackageManager } from "./helpers";
 
+/**
+ * dpkg compatibility command (query/remove/list) backed by the virtual package manager.
+ * @category package
+ * @params ["[-l] [-s pkg] [-L pkg] [-i pkg] [--remove pkg]"]
+ */
 export const dpkgCommand: ShellModule = {
 	name: "dpkg",
 	description: "Debian package manager low-level tool",
-	category: "system",
+	category: "package",
 	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 };
+		if (!pm)
+			return { stderr: "dpkg: package manager not initialised", exitCode: 1 };
 
 		const listFlag = ifFlag(args, ["-l", "--list"]);
 		const statusFlag = ifFlag(args, ["-s", "--status"]);
@@ -18,7 +24,18 @@ export const dpkgCommand: ShellModule = {
 		const purgeFlag = ifFlag(args, ["-P", "--purge"]);
 
 		const { positionals } = parseArgs(args, {
-			flags: ["-l", "--list", "-s", "--status", "-L", "--listfiles", "-r", "--remove", "-P", "--purge"],
+			flags: [
+				"-l",
+				"--list",
+				"-s",
+				"--status",
+				"-L",
+				"--listfiles",
+				"-r",
+				"--remove",
+				"-P",
+				"--purge",
+			],
 		});
 
 		if (listFlag) {
@@ -58,7 +75,8 @@ export const dpkgCommand: ShellModule = {
 
 		if (statusFlag) {
 			const pkgName = positionals[0];
-			if (!pkgName) return { stderr: "dpkg: -s needs a package name", exitCode: 1 };
+			if (!pkgName)
+				return { stderr: "dpkg: -s needs a package name", exitCode: 1 };
 			const info = pm.show(pkgName);
 			if (!info)
 				return {
@@ -70,7 +88,8 @@ export const dpkgCommand: ShellModule = {
 
 		if (listFilesFlag) {
 			const pkgName = positionals[0];
-			if (!pkgName) return { stderr: "dpkg: -L needs a package name", exitCode: 1 };
+			if (!pkgName)
+				return { stderr: "dpkg: -L needs a package name", exitCode: 1 };
 			const installed = pm.listInstalled().find((p) => p.name === pkgName);
 			if (!installed)
 				return {
@@ -85,7 +104,8 @@ export const dpkgCommand: ShellModule = {
 		if (removeFlag || purgeFlag) {
 			if (authUser !== "root")
 				return {
-					stderr: "dpkg: error: requested operation requires superuser privilege",
+					stderr:
+						"dpkg: error: requested operation requires superuser privilege",
 					exitCode: 2,
 				};
 			if (positionals.length === 0)
@@ -114,11 +134,15 @@ export const dpkgCommand: ShellModule = {
 export const dpkgQueryCommand: ShellModule = {
 	name: "dpkg-query",
 	description: "Show information about installed packages",
-	category: "system",
+	category: "package",
 	params: ["-W [pkg] | -l [pattern]"],
 	run: ({ args, shell }) => {
 		const pm = getPackageManager(shell);
-		if (!pm) return { stderr: "dpkg-query: package manager not initialised", exitCode: 1 };
+		if (!pm)
+			return {
+				stderr: "dpkg-query: package manager not initialised",
+				exitCode: 1,
+			};
 
 		const listFlag = ifFlag(args, ["-l"]);
 		const showFlag = ifFlag(args, ["-W", "--show"]);
@@ -135,9 +159,7 @@ export const dpkgQueryCommand: ShellModule = {
 
 			if (showFlag) {
 				return {
-					stdout: filtered
-						.map((p) => `${p.name}\t${p.version}`)
-						.join("\n"),
+					stdout: filtered.map((p) => `${p.name}\t${p.version}`).join("\n"),
 					exitCode: 0,
 				};
 			}

package/src/commands/du.ts

@@ -13,22 +13,34 @@ export const duCommand: ShellModule = {
 		const target = args.find((a) => !a.startsWith("-")) ?? ".";
 		const p = resolvePath(cwd, target);
 
-		const fmt = (b: number) => human ? `${(b / 1024).toFixed(1)}K` : String(Math.ceil(b / 1024));
+		const fmt = (b: number) =>
+			human ? `${(b / 1024).toFixed(1)}K` : String(Math.ceil(b / 1024));
 
-		if (!shell.vfs.exists(p)) return { stderr: `du: ${target}: No such file or directory`, exitCode: 1 };
+		if (!shell.vfs.exists(p))
+			return {
+				stderr: `du: ${target}: No such file or directory`,
+				exitCode: 1,
+			};
 
 		if (summary || shell.vfs.stat(p).type === "file") {
-			return { stdout: `${fmt(shell.vfs.getUsageBytes(p))}\t${target}`, exitCode: 0 };
+			return {
+				stdout: `${fmt(shell.vfs.getUsageBytes(p))}\t${target}`,
+				exitCode: 0,
+			};
 		}
 
 		const lines: string[] = [];
 		const walk = (dir: string, rel: string) => {
 			let total = 0;
 			for (const e of shell.vfs.list(dir)) {
-				const full = `${dir}/${e}`, r = `${rel}/${e}`;
+				const full = `${dir}/${e}`,
+					r = `${rel}/${e}`;
 				const st = shell.vfs.stat(full);
 				if (st.type === "directory") total += walk(full, r);
-				else { total += st.size; if (!summary) lines.push(`${fmt(st.size)}\t${r}`); }
+				else {
+					total += st.size;
+					if (!summary) lines.push(`${fmt(st.size)}\t${r}`);
+				}
 			}
 			lines.push(`${fmt(total)}\t${rel}`);
 			return total;

package/src/commands/echo.ts

@@ -1,5 +1,6 @@
 import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
+import { expandSync } from "../utils/expand";
 
 /**
  * Expand escape sequences for `echo -e`.
@@ -15,27 +16,39 @@ function expandEscapes(text: string): string {
 		.replace(/\\b/g, "\x08")
 		.replace(/\\f/g, "\x0C")
 		.replace(/\\v/g, "\x0B")
-		.replace(/\\0(\d{1,3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)));
+		.replace(/\\0(\d{1,3})/g, (_, oct) =>
+			String.fromCharCode(parseInt(oct, 8)),
+		);
 }
 
+/**
+ * Echo text to stdout with shell-style expansion and escape support.
+ * @category shell
+ * @params ["[-n] [-e] [text...]"]
+ */
 export const echoCommand: ShellModule = {
 	name: "echo",
 	description: "Display text",
 	category: "shell",
 	params: ["[-n] [-e] [text...]"],
 	run: ({ args, stdin, env }) => {
-		const { flags, positionals } = parseArgs(args, { flags: ["-n", "-e", "-E"] });
+		const { flags, positionals } = parseArgs(args, {
+			flags: ["-n", "-e", "-E"],
+		});
 		const noNewline = flags.has("-n");
-		const escapes  = flags.has("-e");
+		const escapes = flags.has("-e");
 
-		const rawText = positionals.length > 0 ? positionals.join(" ") : (stdin ?? "");
+		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] ?? "",
+		// Full expansion: $? ${#VAR} $((expr)) ~ ${VAR:-def} $VAR etc.
+		// $(cmd) is already resolved upstream by runCommand before echo.run is called.
+		const expanded = expandSync(
+			rawText,
+			env?.vars ?? {},
+			env?.lastExitCode ?? 0,
 		);
-
-		const text = escapes ? expandEscapes(varsExpanded) : varsExpanded;
+		const text = escapes ? expandEscapes(expanded) : expanded;
 
 		return {
 			stdout: noNewline ? text : `${text}\n`,

package/src/commands/env.ts

@@ -1,6 +1,11 @@
 /** biome-ignore-all lint/style/useNamingConvention: ENV VARS */
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Print environment variables for the current session.
+ * @category shell
+ * @params []
+ */
 export const envCommand: ShellModule = {
 	name: "env",
 	description: "Print environment variables",
@@ -8,6 +13,11 @@ export const envCommand: ShellModule = {
 	params: [],
 	run: ({ env, authUser }) => {
 		const vars = { ...env.vars, USER: authUser, HOME: `/home/${authUser}` };
-		return { stdout: Object.entries(vars).map(([k, v]) => `${k}=${v}`).join("\n"), exitCode: 0 };
+		return {
+			stdout: Object.entries(vars)
+				.map(([k, v]) => `${k}=${v}`)
+				.join("\n"),
+			exitCode: 0,
+		};
 	},
 };

package/src/commands/exit.ts

@@ -1,8 +1,18 @@
 import type { ShellModule } from "../types/commands";
 
+/**
+ * Exit the current shell session (closeSession flag).
+ * @category shell
+ * @params ["[code]"]
+ */
 export const exitCommand: ShellModule = {
 	name: "exit",
 	aliases: ["bye"],
-	params: [],
-	run: () => ({ closeSession: true, exitCode: 0 }),
+	description: "Exit the shell session",
+	category: "shell",
+	params: ["[code]"],
+	run: ({ args }) => ({
+		closeSession: true,
+		exitCode: parseInt(args[0] ?? "0", 10) || 0,
+	}),
 };

package/src/commands/export.ts

@@ -7,7 +7,9 @@ export const exportCommand: ShellModule = {
 	params: ["[VAR=value]"],
 	run: ({ args, env }) => {
 		if (args.length === 0) {
-			const out = Object.entries(env.vars).map(([k, v]) => `declare -x ${k}="${v}"`).join("\n");
+			const out = Object.entries(env.vars)
+				.map(([k, v]) => `declare -x ${k}="${v}"`)
+				.join("\n");
 			return { stdout: out, exitCode: 0 };
 		}
 		for (const arg of args) {

package/src/commands/find.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Find files and directories by name and type with minimal pattern support.
+ * @category files
+ * @params ["[path] [-name <pattern>] [-type f|d]"]
+ */
 export const findCommand: ShellModule = {
 	name: "find",
 	description: "Search for files",

package/src/commands/free.ts

@@ -2,6 +2,11 @@ import * as os from "node:os";
 import type { ShellModule } from "../types/commands";
 import { ifFlag } from "./command-helpers";
 
+/**
+ * Display memory usage information (human / MB / GB options).
+ * @category system
+ * @params ["[-h] [-m] [-g]"]
+ */
 export const freeCommand: ShellModule = {
 	name: "free",
 	description: "Display amount of free and used memory",
@@ -22,8 +27,10 @@ export const freeCommand: ShellModule = {
 
 		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`;
+				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)));

package/src/commands/grep.ts

@@ -2,13 +2,20 @@ import type { ShellModule } from "../types/commands";
 import { parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Search for a regex pattern in files or stdin with common flags.
+ * @category text
+ * @params ["[-i] [-v] [-n] [-r] <pattern> [file...]"]
+ */
 export const grepCommand: ShellModule = {
 	name: "grep",
 	description: "Search text patterns",
 	category: "text",
 	params: ["[-i] [-v] [-n] [-r] <pattern> [file...]"],
 	run: ({ authUser, shell, cwd, args, stdin }) => {
-		const { flags, positionals } = parseArgs(args, { flags: ["-i", "-v", "-n", "-r"] });
+		const { flags, positionals } = parseArgs(args, {
+			flags: ["-i", "-v", "-n", "-r"],
+		});
 		const caseInsensitive = flags.has("-i");
 		const invertMatch = flags.has("-v");
 		const showLineNumbers = flags.has("-n");
@@ -80,7 +87,10 @@ export const grepCommand: ShellModule = {
 					const prefix = resolvedPaths.length > 1 ? `${file}:` : "";
 					results.push(...matchLines(content, prefix));
 				} catch {
-					return { stderr: `grep: ${file}: No such file or directory`, exitCode: 1 };
+					return {
+						stderr: `grep: ${file}: No such file or directory`,
+						exitCode: 1,
+					};
 				}
 			}
 		}

package/src/commands/gzip.ts

@@ -1,6 +1,11 @@
 import type { ShellModule } from "../types/commands";
 import { resolvePath } from "./helpers";
 
+/**
+ * Compress files using gzip (stores in VFS as compressed content).
+ * @category archive
+ * @params ["<file>"]
+ */
 export const gzipCommand: ShellModule = {
 	name: "gzip",
 	description: "Compress files",
@@ -10,12 +15,24 @@ export const gzipCommand: ShellModule = {
 		const file = args[0];
 		if (!file) return { stderr: "gzip: no file specified", exitCode: 1 };
 		const p = resolvePath(cwd, file);
-		try { shell.vfs.compressFile(p); return { exitCode: 0 }; }
-		catch { return { stderr: `gzip: ${file}: No such file or directory`, exitCode: 1 }; }
+		try {
+			shell.vfs.compressFile(p);
+			return { exitCode: 0 };
+		} catch {
+			return {
+				stderr: `gzip: ${file}: No such file or directory`,
+				exitCode: 1,
+			};
+		}
 	},
 };
 
 export const gunzipCommand: ShellModule = {
+	/**
+	 * Decompress gzip files (or zcat alias).
+	 * @category archive
+	 * @params ["<file>"]
+	 */
 	name: "gunzip",
 	description: "Decompress files",
 	category: "archive",
@@ -25,7 +42,14 @@ export const gunzipCommand: ShellModule = {
 		const file = args[0];
 		if (!file) return { stderr: "gunzip: no file specified", 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 }; }
+		try {
+			shell.vfs.decompressFile(p);
+			return { exitCode: 0 };
+		} catch {
+			return {
+				stderr: `gunzip: ${file}: No such file or directory`,
+				exitCode: 1,
+			};
+		}
 	},
 };

package/src/commands/head.ts

@@ -2,6 +2,11 @@ import type { ShellModule } from "../types/commands";
 import { getFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
 
+/**
+ * Output the first part of files or stdin (head).
+ * @category text
+ * @params ["[-n <lines>] [file...]"]
+ */
 export const headCommand: ShellModule = {
 	name: "head",
 	description: "Output first lines",