typescript-virtual-container 1.2.5 → 1.2.6

package/src/commands/sh.ts

@@ -1,57 +1,206 @@
-import type { CommandContext, ShellModule } from "../types/commands";
-import { getArg, getFlag } from "./command-helpers";
+import type { CommandContext, CommandResult, ShellModule } from "../types/commands";
+import { getArg, ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
 import { runCommand } from "./index";
 
-/** Simple shell script executor with basic variable support */
-export const shCommand: ShellModule = {
-	name: "sh",
-	params: ["-c <script>", "[<file>]"],
-	aliases: ["bash"],
-	run: async (ctx: CommandContext) => {
-		const { args, authUser, hostname, mode, cwd } = ctx;
-		// Handle -c option: sh -c "command"
-		if (getFlag(args, "-c") && args.length >= 2) {
-			const script = getArg(args, 1) ?? "";
-			if (!script) {
-				return { stderr: "sh: -c requires a script", exitCode: 1 };
+/** Expand $VAR and ${VAR:-default} in a line using the current env */
+function expandVars(line: string, env: Record<string, string>, lastExit: number): string {
+	return line
+		.replace(/\$\?/g, String(lastExit))
+		.replace(/\$\{([^}:]+):-([^}]*)\}/g, (_, n, d) => env[n] ?? d)
+		.replace(/\$\{([^}]+)\}/g, (_, n) => env[n] ?? "")
+		.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, n) => env[n] ?? "")
+		.replace(/^~(\/|$)/, `${env.HOME ?? "/home/user"}$1`);
+}
+
+type Block =
+	| { type: "if"; cond: string; then: string[]; elif: Array<{ cond: string; body: string[] }>; else_: string[] }
+	| { type: "for"; var: string; list: string; body: string[] }
+	| { type: "while"; cond: string; body: string[] }
+	| { type: "cmd"; line: string };
+
+/** Very small shell interpreter: supports if/elif/else/fi, for/do/done, while/do/done */
+function parseBlocks(lines: string[]): Block[] {
+	const blocks: Block[] = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i]!.trim();
+		if (!line || line.startsWith("#")) { i++; continue; }
+
+		if (line.startsWith("if ") || line === "if") {
+			const cond = line.replace(/^if\s+/, "").replace(/;\s*then\s*$/, "").trim();
+			const thenLines: string[] = [];
+			const elifBlocks: Array<{ cond: string; body: string[] }> = [];
+			const elseLines: string[] = [];
+			let section: "then" | "elif" | "else" = "then";
+			let elifCond = "";
+			i++;
+			while (i < lines.length && lines[i]?.trim() !== "fi") {
+				const l = lines[i]!.trim();
+				if (l.startsWith("elif ")) { section = "elif"; elifCond = l.replace(/^elif\s+/, "").replace(/;\s*then\s*$/, "").trim(); elifBlocks.push({ cond: elifCond, body: [] }); }
+				else if (l === "else") { section = "else"; }
+				else if (l !== "then") {
+					if (section === "then") thenLines.push(l);
+					else if (section === "elif" && elifBlocks.length > 0) elifBlocks[elifBlocks.length - 1]!.body.push(l);
+					else elseLines.push(l);
+				}
+				i++;
 			}
-			const scriptArgs = args.slice(2);
-
-			// Split by semicolon and newline
-			const lines = script
-				.split(/[;\n]/)
-				.map((line) => line.trim())
-				.filter((line) => line && !line.startsWith("#"));
-
-			let output = "";
-			const exitCode = 0;
-
-			for (const line of lines) {
-				// Simple variable substitution
-				let command = line;
-				for (let i = 0; i < scriptArgs.length; i++) {
-					const arg = scriptArgs[i] ?? "";
-					command = command.replaceAll(`$${i}`, arg);
+			blocks.push({ type: "if", cond, then: thenLines, elif: elifBlocks, else_: elseLines });
+		} else if (line.startsWith("for ")) {
+			const m = line.match(/^for\s+(\w+)\s+in\s+(.+?)(?:\s*;\s*do)?$/);
+			if (m) {
+				const body: string[] = [];
+				i++;
+				while (i < lines.length && lines[i]?.trim() !== "done") {
+					const l = lines[i]!.trim();
+					if (l !== "do") body.push(l);
+					i++;
 				}
-				command = command.replaceAll("$@", scriptArgs.join(" "));
+				blocks.push({ type: "for", var: m[1]!, list: m[2]!, body });
+			} else { blocks.push({ type: "cmd", line }); }
+		} else if (line.startsWith("while ")) {
+			const cond = line.replace(/^while\s+/, "").replace(/;\s*do\s*$/, "").trim();
+			const body: string[] = [];
+			i++;
+			while (i < lines.length && lines[i]?.trim() !== "done") {
+				const l = lines[i]!.trim();
+				if (l !== "do") body.push(l);
+				i++;
+			}
+			blocks.push({ type: "while", cond, body });
+		} else {
+			blocks.push({ type: "cmd", line });
+		}
+		i++;
+	}
+	return blocks;
+}
 
-				// Execute the command
-				const result = await Promise.resolve(
-					runCommand(command, authUser, hostname, mode, cwd, ctx.shell),
-				);
+async function evalCondition(cond: string, ctx: CommandContext): Promise<boolean> {
+	const expanded = expandVars(cond, ctx.env.vars, ctx.env.lastExitCode);
+	// test -f / test -d / [ ... ]
+	const testMatch = expanded.match(/^\[?\s*(.+?)\s*\]?$/);
+	if (testMatch) {
+		const expr = testMatch[1]!;
+		// -f file
+		const fTest = expr.match(/^-([fdeznr])\s+(.+)$/);
+		if (fTest) {
+			const [, flag, arg] = fTest;
+			const p = resolvePath(ctx.cwd, arg!);
+			if (flag === "f") return ctx.shell.vfs.exists(p) && ctx.shell.vfs.stat(p).type === "file";
+			if (flag === "d") return ctx.shell.vfs.exists(p) && ctx.shell.vfs.stat(p).type === "directory";
+			if (flag === "e") return ctx.shell.vfs.exists(p);
+			if (flag === "z") return (arg ?? "").length === 0;
+			if (flag === "n") return (arg ?? "").length > 0;
+		}
+		// string comparison
+		const cmpMatch = expr.match(/^"?([^"]*)"?\s*(==|!=|=|<|>)\s*"?([^"]*)"?$/);
+		if (cmpMatch) {
+			const [, a, op, b] = cmpMatch;
+			if (op === "==" || op === "=") return a === b;
+			if (op === "!=") return a !== b;
+		}
+		// numeric
+		const numMatch = expr.match(/^(\S+)\s+(-eq|-ne|-lt|-le|-gt|-ge)\s+(\S+)$/);
+		if (numMatch) {
+			const [, a, op, b] = numMatch;
+			const na = Number(a), nb = Number(b);
+			if (op === "-eq") return na === nb;
+			if (op === "-ne") return na !== nb;
+			if (op === "-lt") return na < nb;
+			if (op === "-le") return na <= nb;
+			if (op === "-gt") return na > nb;
+			if (op === "-ge") return na >= nb;
+		}
+	}
+	// fallback: run command and check exit code
+	const r = await runCommand(expanded, ctx.authUser, ctx.hostname, ctx.mode, ctx.cwd, ctx.shell, undefined, ctx.env);
+	return (r.exitCode ?? 0) === 0;
+}
 
-				if (result.stdout) {
-					output += `${result.stdout}\n`;
-				}
+async function runBlocks(blocks: Block[], ctx: CommandContext): Promise<CommandResult> {
+	let lastResult: CommandResult = { exitCode: 0 };
+	let output = "";
 
-				if (result.stderr) {
-					return { stderr: result.stderr, exitCode: result.exitCode ?? 1 };
+	for (const block of blocks) {
+		if (block.type === "cmd") {
+			const expanded = expandVars(block.line, ctx.env.vars, ctx.env.lastExitCode);
+			const r = await runCommand(expanded, ctx.authUser, ctx.hostname, ctx.mode, ctx.cwd, ctx.shell, undefined, ctx.env);
+			ctx.env.lastExitCode = r.exitCode ?? 0;
+			if (r.stdout) output += `${r.stdout}\n`;
+			if (r.stderr) return { ...r, stdout: output.trim() };
+			lastResult = r;
+		} else if (block.type === "if") {
+			let ran = false;
+			if (await evalCondition(block.cond, ctx)) {
+				const sub = await runBlocks(parseBlocks(block.then), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				ran = true;
+			} else {
+				for (const elif of block.elif) {
+					if (await evalCondition(elif.cond, ctx)) {
+						const sub = await runBlocks(parseBlocks(elif.body), ctx);
+						if (sub.stdout) output += `${sub.stdout}\n`;
+						ran = true; break;
+					}
+				}
+				if (!ran && block.else_.length > 0) {
+					const sub = await runBlocks(parseBlocks(block.else_), ctx);
+					if (sub.stdout) output += `${sub.stdout}\n`;
 				}
 			}
+		} else if (block.type === "for") {
+			const listExpanded = expandVars(block.list, ctx.env.vars, ctx.env.lastExitCode);
+			const items = listExpanded.trim().split(/\s+/);
+			for (const item of items) {
+				ctx.env.vars[block.var] = item;
+				const sub = await runBlocks(parseBlocks(block.body), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				if (sub.closeSession) return sub;
+			}
+		} else if (block.type === "while") {
+			let iterations = 0;
+			while (iterations < 1000 && await evalCondition(block.cond, ctx)) {
+				const sub = await runBlocks(parseBlocks(block.body), ctx);
+				if (sub.stdout) output += `${sub.stdout}\n`;
+				if (sub.closeSession) return sub;
+				iterations++;
+			}
+		}
+	}
+	return { ...lastResult, stdout: output.trim() || lastResult.stdout };
+}
+
+export const shCommand: ShellModule = {
+	name: "sh",
+	aliases: ["bash"],
+	description: "Execute shell script or command",
+	category: "shell",
+	params: ["-c <script>", "[<file>]"],
+	run: async (ctx: CommandContext) => {
+		const { args, authUser, shell, cwd } = ctx;
+
+		// sh -c "inline script"
+		if (ifFlag(args, "-c")) {
+			const script = getArg(args, 1) ?? "";
+			if (!script) return { stderr: "sh: -c requires a script", exitCode: 1 };
+			const lines = script.split(/[;\n]/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+			const blocks = parseBlocks(lines);
+			return runBlocks(blocks, ctx);
+		}
 
-			return { stdout: output.trim(), exitCode };
+		// sh <file>
+		const fileArg = args[0];
+		if (fileArg) {
+			const p = resolvePath(cwd, fileArg);
+			if (!shell.vfs.exists(p)) return { stderr: `sh: ${fileArg}: No such file or directory`, exitCode: 1 };
+			const content = shell.vfs.readFile(p);
+			const lines = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+			const blocks = parseBlocks(lines);
+			return runBlocks(blocks, ctx);
 		}
 
-		return { stderr: "sh: invalid usage", exitCode: 1 };
+		return { stderr: "sh: invalid usage. Use: sh -c 'cmd' or sh <file>", exitCode: 1 };
 	},
 };

package/src/commands/sleep.ts

@@ -0,0 +1,14 @@
+import type { ShellModule } from "../types/commands";
+
+export const sleepCommand: ShellModule = {
+	name: "sleep",
+	description: "Delay execution",
+	category: "system",
+	params: ["<seconds>"],
+	run: async ({ args }) => {
+		const secs = parseFloat(args[0] ?? "1");
+		if (Number.isNaN(secs) || secs < 0) return { stderr: "sleep: invalid time", exitCode: 1 };
+		await new Promise((r) => setTimeout(r, secs * 1000));
+		return { exitCode: 0 };
+	},
+};

package/src/commands/sort.ts

@@ -0,0 +1,37 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { assertPathAccess, resolvePath } from "./helpers";
+
+export const sortCommand: ShellModule = {
+	name: "sort",
+	description: "Sort lines of text",
+	category: "text",
+	params: ["[-r] [-n] [-u] [-k <col>] [file...]"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const reverse = ifFlag(args, ["-r"]);
+		const numeric = ifFlag(args, ["-n"]);
+		const unique = ifFlag(args, ["-u"]);
+		const files = args.filter((a) => !a.startsWith("-"));
+
+		const getContent = (): string => {
+			if (files.length > 0) {
+				return files.map((f) => {
+					try {
+						assertPathAccess(authUser, resolvePath(cwd, f), "sort");
+						return shell.vfs.readFile(resolvePath(cwd, f));
+					} catch { return ""; }
+				}).join("\n");
+			}
+			return stdin ?? "";
+		};
+
+		const lines = getContent().split("\n").filter(Boolean);
+		const sorted = [...lines].sort((a, b) => {
+			if (numeric) return Number(a) - Number(b);
+			return a.localeCompare(b);
+		});
+		const result = reverse ? sorted.reverse() : sorted;
+		const out = unique ? [...new Set(result)] : result;
+		return { stdout: out.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/su.ts

@@ -3,6 +3,8 @@ import { getArg } from "./command-helpers";
 
 export const suCommand: ShellModule = {
 	name: "su",
+	description: "Switch user",
+	category: "users",
 	params: ["- <username>"],
 	run: ({ authUser, shell, args }) => {
 		const users = shell.users!;

package/src/commands/sudo.ts

@@ -21,6 +21,8 @@ function parseSudoArgs(args: string[]): {
 }
 export const sudoCommand: ShellModule = {
 	name: "sudo",
+	description: "Execute as superuser",
+	category: "users",
 	params: ["<command...>"],
 	run: async ({ authUser, hostname, mode, cwd, shell, args }) => {
 		const { targetUser, loginShell, commandLine } = parseSudoArgs(args);

package/src/commands/tail.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const tailCommand: ShellModule = {
 	name: "tail",
+	description: "Output last lines",
+	category: "text",
 	params: ["[-n <lines>] [file...]"],
 	run: ({ authUser, shell, cwd, args, stdin }) => {
 		const nArg = getFlag(args, ["-n"]);

package/src/commands/tar.ts

@@ -0,0 +1,58 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
+
+export const tarCommand: ShellModule = {
+	name: "tar",
+	description: "Archive utility",
+	category: "archive",
+	params: ["[-czf|-xzf|-tf] <archive> [files...]"],
+	run: ({ authUser, shell, cwd, args }) => {
+		const create = ifFlag(args, ["-c"]);
+		const extract = ifFlag(args, ["-x"]);
+		const list = ifFlag(args, ["-t"]);
+		const fFlag = args.findIndex((a) => a.includes("f"));
+		const archiveName = fFlag !== -1 ? args[fFlag + 1] : args.find((a) => a.endsWith(".tar") || a.endsWith(".tar.gz") || a.endsWith(".tgz"));
+
+		if (!archiveName) return { stderr: "tar: no archive specified", exitCode: 1 };
+		const archivePath = resolvePath(cwd, archiveName);
+
+		if (create) {
+			const fileArgs = args.filter((a) => !a.startsWith("-") && a !== archiveName);
+			const entries: Record<string, string> = {};
+			for (const f of fileArgs) {
+				const p = resolvePath(cwd, f);
+				try {
+					const stat = shell.vfs.stat(p);
+					if (stat.type === "file") entries[f] = shell.vfs.readFile(p);
+					else {
+						const walk = (dir: string, prefix: string) => {
+							for (const e of shell.vfs.list(dir)) {
+								const full = `${dir}/${e}`, rel = `${prefix}/${e}`;
+								const s = shell.vfs.stat(full);
+								if (s.type === "file") entries[rel] = shell.vfs.readFile(full);
+								else walk(full, rel);
+							}
+						};
+						walk(p, f);
+					}
+				} catch { return { stderr: `tar: ${f}: No such file or directory`, exitCode: 1 }; }
+			}
+			shell.writeFileAsUser(authUser, archivePath, JSON.stringify(entries));
+			return { exitCode: 0 };
+		}
+
+		if (list || extract) {
+			let entries: Record<string, string>;
+			try { entries = JSON.parse(shell.vfs.readFile(archivePath)); }
+			catch { return { stderr: `tar: ${archiveName}: cannot open archive`, exitCode: 1 }; }
+			if (list) return { stdout: Object.keys(entries).join("\n"), exitCode: 0 };
+			for (const [name, content] of Object.entries(entries)) {
+				shell.writeFileAsUser(authUser, resolvePath(cwd, name), content);
+			}
+			return { exitCode: 0 };
+		}
+
+		return { stderr: "tar: must specify -c, -x, or -t", exitCode: 1 };
+	},
+};

package/src/commands/tee.ts

@@ -0,0 +1,25 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+import { resolvePath } from "./helpers";
+
+export const teeCommand: ShellModule = {
+	name: "tee",
+	description: "Read stdin, write to stdout and files",
+	category: "text",
+	params: ["[-a] <file...>"],
+	run: ({ authUser, shell, cwd, args, stdin }) => {
+		const append = ifFlag(args, ["-a"]);
+		const files = args.filter((a) => !a.startsWith("-"));
+		const input = stdin ?? "";
+		for (const f of files) {
+			const p = resolvePath(cwd, f);
+			if (append) {
+				const existing = (() => { try { return shell.vfs.readFile(p); } catch { return ""; } })();
+				shell.writeFileAsUser(authUser, p, existing + input);
+			} else {
+				shell.writeFileAsUser(authUser, p, input);
+			}
+		}
+		return { stdout: input, exitCode: 0 };
+	},
+};

package/src/commands/touch.ts

@@ -3,6 +3,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const touchCommand: ShellModule = {
 	name: "touch",
+	description: "Create or update files",
+	category: "files",
 	params: ["<file>"],
 	run: ({ authUser, shell, cwd, args }) => {
 		if (args.length === 0) {

package/src/commands/tr.ts

@@ -0,0 +1,24 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+
+export const trCommand: ShellModule = {
+	name: "tr",
+	description: "Translate or delete characters",
+	category: "text",
+	params: ["[-d] <set1> [set2]"],
+	run: ({ args, stdin }) => {
+		const del = ifFlag(args, ["-d"]);
+		const positionals = args.filter((a) => !a.startsWith("-"));
+		const set1 = positionals[0] ?? "";
+		const set2 = positionals[1] ?? "";
+		let input = stdin ?? "";
+		if (del) {
+			for (const c of set1) input = input.split(c).join("");
+		} else if (set2) {
+			for (let i = 0; i < set1.length; i++) {
+				input = input.split(set1[i]!).join(set2[i] ?? set2[set2.length - 1] ?? "");
+			}
+		}
+		return { stdout: input, exitCode: 0 };
+	},
+};

package/src/commands/tree.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const treeCommand: ShellModule = {
 	name: "tree",
+	description: "Display directory tree",
+	category: "navigation",
 	params: ["[path]"],
 	run: ({ authUser, shell, cwd, args }) => {
 		const target = resolvePath(cwd, getArg(args, 0) ?? cwd);

package/src/commands/uname.ts

@@ -0,0 +1,20 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+
+export const unameCommand: ShellModule = {
+	name: "uname",
+	description: "Print system information",
+	category: "system",
+	params: ["[-a] [-s] [-r] [-m]"],
+	run: ({ shell, args }) => {
+		const all = ifFlag(args, ["-a"]);
+		const sysname = "Linux";
+		const release = shell.properties?.kernel ?? "5.15.0";
+		const machine = shell.properties?.arch ?? "x86_64";
+		const hostname = shell.hostname;
+		if (all) return { stdout: `${sysname} ${hostname} ${release} #1 SMP ${machine} GNU/Linux`, exitCode: 0 };
+		if (ifFlag(args, ["-r"])) return { stdout: release, exitCode: 0 };
+		if (ifFlag(args, ["-m"])) return { stdout: machine, exitCode: 0 };
+		return { stdout: sysname, exitCode: 0 };
+	},
+};

package/src/commands/uniq.ts

@@ -0,0 +1,28 @@
+import type { ShellModule } from "../types/commands";
+import { ifFlag } from "./command-helpers";
+
+export const uniqCommand: ShellModule = {
+	name: "uniq",
+	description: "Report or filter out repeated lines",
+	category: "text",
+	params: ["[-c] [-d] [-u] [file]"],
+	run: ({ args, stdin }) => {
+		const count = ifFlag(args, ["-c"]);
+		const dupOnly = ifFlag(args, ["-d"]);
+		const uniqOnly = ifFlag(args, ["-u"]);
+		const lines = (stdin ?? "").split("\n");
+		const out: string[] = [];
+		let i = 0;
+		while (i < lines.length) {
+			let j = i;
+			while (j < lines.length && lines[j] === lines[i]) j++;
+			const n = j - i;
+			const line = lines[i]!;
+			if (dupOnly && n === 1) { i = j; continue; }
+			if (uniqOnly && n > 1) { i = j; continue; }
+			out.push(count ? `${String(n).padStart(4)} ${line}` : line);
+			i = j;
+		}
+		return { stdout: out.join("\n"), exitCode: 0 };
+	},
+};

package/src/commands/unset.ts

@@ -1,19 +1,12 @@
 import type { ShellModule } from "../types/commands";
-import { setEnvVar } from "./set";
 
 export const unsetCommand: ShellModule = {
 	name: "unset",
-	params: ["<VAR...>"],
-	run: ({ args }) => {
-		if (args.length === 0) {
-			return { stderr: "unset: missing variable name", exitCode: 1 };
-		}
-
-		// Unset (remove) all specified variables
-		for (const varName of args) {
-			setEnvVar(varName, "");
-		}
-
+	description: "Remove shell variable",
+	category: "shell",
+	params: ["<VAR>"],
+	run: ({ args, env }) => {
+		for (const name of args) delete env.vars[name];
 		return { exitCode: 0 };
 	},
 };

package/src/commands/wc.ts

@@ -4,6 +4,8 @@ import { assertPathAccess, resolvePath } from "./helpers";
 
 export const wcCommand: ShellModule = {
 	name: "wc",
+	description: "Count words/lines/bytes",
+	category: "text",
 	params: ["[-l] [-w] [-c] [file...]"],
 	run: ({ authUser, shell, cwd, args, stdin }) => {
 		const lines = ifFlag(args, ["-l"]);

package/src/commands/wget.ts

@@ -82,6 +82,8 @@ function runHostWget(args: string[]): Promise<{
 
 export const wgetCommand: ShellModule = {
 	name: "wget",
+	description: "File downloader",
+	category: "network",
 	params: ["[url]"],
 	run: async ({ authUser, cwd, args, shell }) => {
 		const { flagsWithValues, positionals } = parseArgs(args, {

package/src/commands/who.ts

@@ -3,6 +3,8 @@ import type { ShellModule } from "../types/commands";
 
 export const whoCommand: ShellModule = {
 	name: "who",
+	description: "Show active sessions",
+	category: "system",
 	params: [],
 	run: ({ shell }) => {
 		const lines = shell.users.listActiveSessions().map((session) => {

package/src/commands/whoami.ts

@@ -2,6 +2,8 @@ import type { ShellModule } from "../types/commands";
 
 export const whoamiCommand: ShellModule = {
 	name: "whoami",
+	description: "Print current user",
+	category: "system",
 	params: [],
 	run: ({ authUser }) => ({ stdout: authUser, exitCode: 0 }),
 };

package/src/commands/xargs.ts

@@ -0,0 +1,17 @@
+import type { ShellModule } from "../types/commands";
+import { runCommand } from "./index";
+
+export const xargsCommand: ShellModule = {
+	name: "xargs",
+	description: "Build and execute command lines from stdin",
+	category: "text",
+	params: ["[command] [args...]"],
+	run: async ({ authUser, hostname, mode, cwd, args, stdin, shell, env }) => {
+		const baseCmd = args[0] ?? "echo";
+		const extraArgs = args.slice(1);
+		const items = (stdin ?? "").trim().split(/\s+/).filter(Boolean);
+		if (items.length === 0) return { exitCode: 0 };
+		const fullCmd = [baseCmd, ...extraArgs, ...items].join(" ");
+		return runCommand(fullCmd, authUser, hostname, mode, cwd, shell, undefined, env);
+	},
+};

package/src/types/commands.ts

@@ -57,6 +57,14 @@ export interface NanoEditorSession {
 	initialContent: string;
 }
 
+/** Per-session shell environment (variables, last exit code). */
+export interface ShellEnv {
+	/** Environment variables visible to commands. */
+	vars: Record<string, string>;
+	/** Exit status of the last executed command. */
+	lastExitCode: number;
+}
+
 /** Runtime context object passed to each command module. */
 export interface CommandContext {
 	/** Authenticated user currently bound to stream. */
@@ -77,6 +85,8 @@ export interface CommandContext {
 	stdin?: string;
 	/** Current working directory for command execution. */
 	cwd: string;
+	/** Per-session environment available to command modules. */
+	env: ShellEnv;
 }
 
 /** Contract implemented by each shell command module. */
@@ -89,6 +99,10 @@ export interface ShellModule {
 	run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>;
 	/** Optional alternative command names. */
 	aliases?: string[];
+	/** Short description shown in `help`. */
+	description?: string;
+	/** Category used for grouped help output. */
+	category?: string;
 }
 
 /** Command return union allowing sync or async handlers. */