typescript-virtual-container 1.5.11 → 1.6.1

package/dist/commands/netcat.js

@@ -0,0 +1,64 @@
+/**
+ * Netcat network utility
+ * @category net
+ * @params ["[-l] [-p port] [-v]"]
+ */
+export const ncCommand = {
+    name: "nc",
+    description: "Netcat network utility",
+    category: "net",
+    params: ["[-l] [-p port] [-v]"],
+    run: async ({ args }) => {
+        let mod;
+        try {
+            mod = await import("node:net");
+        }
+        catch {
+            return { stderr: "nc: not available in this environment\n", exitCode: 1 };
+        }
+        const net = mod;
+        const isListen = args.includes("-l");
+        const pIdx = args.indexOf("-p");
+        const port = pIdx !== -1 && args[pIdx + 1] ? parseInt(args[pIdx + 1], 10) : undefined;
+        const verbose = args.includes("-v");
+        if (isListen && port) {
+            return new Promise((resolve) => {
+                const server = net.createServer((socket) => {
+                    let data = "";
+                    socket.on("data", (chunk) => { data += chunk.toString(); });
+                    socket.on("end", () => {
+                        server.close();
+                        resolve({ stdout: data, exitCode: 0 });
+                    });
+                });
+                server.listen(port, () => {
+                    if (verbose) {
+                        resolve({ stdout: `Listening on port ${port}...\n`, exitCode: 0 });
+                    }
+                });
+                setTimeout(() => { server.close(); resolve({ exitCode: 0 }); }, 5000);
+            });
+        }
+        const nonFlag = args.filter((a) => !a.startsWith("-"));
+        const host = nonFlag[0];
+        const portNum = nonFlag[1] ? parseInt(nonFlag[1], 10) : NaN;
+        if (host && !isNaN(portNum)) {
+            return new Promise((resolve) => {
+                const socket = net.createConnection({ host, port: portNum }, () => {
+                    if (verbose) {
+                        resolve({ stdout: `Connected to ${host}:${portNum}\n`, exitCode: 0 });
+                    }
+                    setTimeout(() => { socket.end(); resolve({ exitCode: 0 }); }, 3000);
+                });
+                socket.on("error", () => {
+                    resolve({ stderr: `nc: connection to ${host}:${portNum} failed\n`, exitCode: 1 });
+                });
+                setTimeout(() => { socket.destroy(); resolve({ exitCode: 1 }); }, 5000);
+            });
+        }
+        return {
+            stderr: "nc: missing arguments. Usage: nc [-l] [-p port] [-v] [host] [port]\n",
+            exitCode: 1,
+        };
+    },
+};

package/dist/commands/nice.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Run command with adjusted niceness
+ * @category system
+ * @params ["[-n adjustment] <command> [args...]"]
+ */
+export declare const niceCommand: ShellModule;

package/dist/commands/nice.js

@@ -0,0 +1,22 @@
+import { parseArgs } from "./command-helpers";
+import { runCommand } from "./runtime";
+/**
+ * Run command with adjusted niceness
+ * @category system
+ * @params ["[-n adjustment] <command> [args...]"]
+ */
+export const niceCommand = {
+    name: "nice",
+    description: "Run command with adjusted niceness",
+    category: "system",
+    params: ["[-n adjustment] <command> [args...]"],
+    run: async ({ authUser, hostname, mode, cwd, shell, stdin, env, args }) => {
+        const { positionals } = parseArgs(args, {
+            flagsWithValue: ["-n"],
+        });
+        const cmd = positionals.join(" ");
+        if (!cmd)
+            return { stderr: "nice: missing command\n", exitCode: 1 };
+        return runCommand(cmd, authUser, hostname, mode, cwd, shell, stdin, env);
+    },
+};

package/dist/commands/nohup.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Run command immune to hup signals
+ * @category system
+ * @params ["<command> [args...]"]
+ */
+export declare const nohupCommand: ShellModule;

package/dist/commands/nohup.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./runtime";
+/**
+ * Run command immune to hup signals
+ * @category system
+ * @params ["<command> [args...]"]
+ */
+export const nohupCommand = {
+    name: "nohup",
+    description: "Run command immune to hup signals",
+    category: "system",
+    params: ["<command> [args...]"],
+    run: async ({ authUser, hostname, mode, cwd, shell, stdin, env, args }) => {
+        const cmd = args.join(" ");
+        if (!cmd)
+            return { stderr: "nohup: missing command\n", exitCode: 1 };
+        return runCommand(cmd, authUser, hostname, mode, cwd, shell, stdin, env);
+    },
+};

package/dist/commands/ping.d.ts

@@ -1,6 +1,7 @@
 import type { ShellModule } from "../types/commands";
 /**
- * Send ICMP ECHO_REQUEST packets (mock implementation).
+ * Send ICMP ECHO_REQUEST packets — uses the real host ping when available,
+ * falls back to VirtualNetworkManager simulation in browser or when system ping is absent.
  * @category network
  * @params ["[-c <count>] <host>"]
  */

package/dist/commands/ping.js

@@ -1,28 +1,66 @@
 import { parseArgs } from "./command-helpers";
+const isBrowser = typeof process === "undefined" || typeof process.versions?.node === "undefined";
+/** Lazily import execSync — avoids static import that breaks browser polyfills. */
+async function execPing(count, host) {
+    try {
+        const { execSync } = await import("node:child_process");
+        const output = execSync(`ping -c ${count} ${host}`, {
+            timeout: 30000,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { stdout: output };
+    }
+    catch (err) {
+        const stderrMsg = err instanceof Error ? err.stderr : "";
+        if (stderrMsg)
+            return { stderr: stderrMsg };
+        return null;
+    }
+}
 /**
- * Send ICMP ECHO_REQUEST packets (mock implementation).
+ * Send ICMP ECHO_REQUEST packets — uses the real host ping when available,
+ * falls back to VirtualNetworkManager simulation in browser or when system ping is absent.
  * @category network
  * @params ["[-c <count>] <host>"]
  */
 export const pingCommand = {
     name: "ping",
-    description: "Send ICMP ECHO_REQUEST (mock)",
+    description: "Send ICMP ECHO_REQUEST to network hosts",
     category: "network",
     params: ["[-c <count>] <host>"],
-    run: ({ args }) => {
+    run: async ({ args, shell }) => {
         const { flagsWithValues, positionals } = parseArgs(args, {
             flagsWithValue: ["-c", "-i", "-W"],
         });
         const host = positionals[0] ?? "localhost";
         const countArg = flagsWithValues.get("-c");
         const count = countArg ? Math.max(1, parseInt(countArg, 10) || 4) : 4;
-        const lines = [`PING ${host}: 56 data bytes`];
+        // Try real system ping first (Node.js only)
+        if (!isBrowser) {
+            const result = await execPing(count, host);
+            if (result)
+                return { ...result, exitCode: "stdout" in result ? 0 : 1 };
+        }
+        // Fallback: VirtualNetworkManager simulation
+        const lines = [`PING ${host} (${host === "localhost" ? "127.0.0.1" : host}): 56 data bytes`];
+        let transmitted = 0;
+        let received = 0;
         for (let i = 0; i < count; i++) {
-            const ms = (Math.random() * 10 + 1).toFixed(3);
-            lines.push(`64 bytes from ${host}: icmp_seq=${i} ttl=64 time=${ms} ms`);
+            transmitted++;
+            const latency = shell.network.ping(host);
+            if (latency < 0) {
+                lines.push(`From ${host} icmp_seq=${i} Destination Host Unreachable`);
+            }
+            else {
+                received++;
+                lines.push(`64 bytes from ${host}: icmp_seq=${i} ttl=64 time=${latency.toFixed(3)} ms`);
+            }
         }
+        const lost = transmitted - received;
+        const lossPct = ((lost / transmitted) * 100).toFixed(0);
         lines.push(`--- ${host} ping statistics ---`);
-        lines.push(`${count} packets transmitted, ${count} received, 0% packet loss`);
-        return { stdout: lines.join("\n"), exitCode: 0 };
+        lines.push(`${transmitted} packets transmitted, ${received} received, ${lossPct}% packet loss`);
+        return { stdout: `${lines.join("\n")}\n`, exitCode: 0 };
     },
 };

package/dist/commands/procUtils.d.ts

@@ -0,0 +1,13 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * List process IDs matching a pattern
+ * @category system
+ * @params ["[-f] <pattern>"]
+ */
+export declare const pgrepCommand: ShellModule;
+/**
+ * Kill processes matching a pattern
+ * @category system
+ * @params ["[-f] <pattern>"]
+ */
+export declare const pkillCommand: ShellModule;

package/dist/commands/procUtils.js

@@ -0,0 +1,72 @@
+/**
+ * List process IDs matching a pattern
+ * @category system
+ * @params ["[-f] <pattern>"]
+ */
+export const pgrepCommand = {
+    name: "pgrep",
+    description: "List process IDs matching a pattern",
+    category: "system",
+    params: ["[-f] <pattern>"],
+    run: ({ activeSessions, args }) => {
+        const useFull = args.includes("-f");
+        const pattern = args.find((a) => !a.startsWith("-"));
+        if (!pattern)
+            return { stderr: "pgrep: missing pattern\n", exitCode: 1 };
+        try {
+            const re = new RegExp(pattern);
+            const results = [];
+            for (let i = 0; i < activeSessions.length; i++) {
+                const s = activeSessions[i];
+                const target = useFull
+                    ? `${s.username} ${s.tty} ${s.remoteAddress} ${s.id}`
+                    : s.username;
+                if (re.test(target)) {
+                    results.push(String(1000 + i));
+                }
+            }
+            if (results.length === 0)
+                return { exitCode: 1 };
+            return { stdout: results.join("\n") + "\n", exitCode: 0 };
+        }
+        catch {
+            return { stderr: "pgrep: invalid pattern\n", exitCode: 2 };
+        }
+    },
+};
+/**
+ * Kill processes matching a pattern
+ * @category system
+ * @params ["[-f] <pattern>"]
+ */
+export const pkillCommand = {
+    name: "pkill",
+    description: "Kill processes matching a pattern",
+    category: "system",
+    params: ["[-f] <pattern>"],
+    run: ({ activeSessions, shell, args }) => {
+        const useFull = args.includes("-f");
+        const pattern = args.find((a) => !a.startsWith("-"));
+        if (!pattern)
+            return { stderr: "pkill: missing pattern\n", exitCode: 1 };
+        try {
+            const re = new RegExp(pattern);
+            let killed = 0;
+            for (const s of activeSessions) {
+                const target = useFull
+                    ? `${s.username} ${s.tty} ${s.remoteAddress} ${s.id}`
+                    : s.username;
+                if (re.test(target)) {
+                    shell.users.unregisterSession(s.id);
+                    killed++;
+                }
+            }
+            if (killed === 0)
+                return { exitCode: 1 };
+            return { stdout: `killed ${killed} process(es)\n`, exitCode: 0 };
+        }
+        catch {
+            return { stderr: "pkill: invalid pattern\n", exitCode: 2 };
+        }
+    },
+};

package/dist/commands/pwd.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Print working directory.
+ * @category navigation
+ * @params []
+ */
 export declare const pwdCommand: ShellModule;

package/dist/commands/pwd.js

@@ -1,3 +1,8 @@
+/**
+ * Print working directory.
+ * @category navigation
+ * @params []
+ */
 export const pwdCommand = {
     name: "pwd",
     description: "Print working directory",

package/dist/commands/python.js

@@ -1,7 +1,6 @@
 import { ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
 const VERSION = "Python 3.11.2";
-const _VERSION_SHORT = "3.11.2";
 const VERSION_INFO = "3.11.2 (default, Mar 13 2023, 12:18:29) [GCC 12.2.0]";
 const NONE = { __pytype__: "none" };
 function pyDict(entries = []) {
@@ -1664,7 +1663,6 @@ class Interpreter {
         if (line.startsWith("if ") && line.endsWith(":")) {
             const cond = line.slice(3, -1).trim();
             const body = this.collectBlock(lines, idx + 1, indent);
-            const _skip = body.length + 1;
             if (pyBool(this.pyEval(cond, scope))) {
                 this.execBlock(body, new Map(scope).also?.((s) => {
                     for (const [k, v] of scope)
@@ -1814,7 +1812,6 @@ class Interpreter {
                 else
                     break;
             }
-            let _caughtErr = null;
             try {
                 this.runBlockInScope(tryBody, scope);
                 if (elseBody.length)
@@ -1822,7 +1819,6 @@ class Interpreter {
             }
             catch (e) {
                 if (e instanceof PyError) {
-                    _caughtErr = e;
                     let handled = false;
                     for (const clause of exceptClauses) {
                         if (clause.exc === null ||

package/dist/commands/read.js

@@ -10,7 +10,6 @@ export const readCommand = {
     category: "shell",
     params: ["[-r] [-p prompt] <var...>"],
     run: ({ args, stdin, env }) => {
-        const _promptIdx = args.indexOf("-p");
         const varNames = args.filter((a, i) => a !== "-r" && a !== "-p" && args[i - 1] !== "-p");
         // In non-interactive context, read from stdin pipe
         const input = (stdin ?? "").split("\n")[0] ?? "";

package/dist/commands/registry.d.ts

@@ -1,7 +1,44 @@
 /** biome-ignore-all lint/style/useNamingConvention: ENV VARIABLES */
 import type { CommandContext, CommandResult, ShellModule } from "../types/commands";
+/**
+ * Registers a command module so it can be called from the shell.
+ * The module's name and aliases are lowercased and trimmed; names must be
+ * non-empty and contain no spaces. Updates the registry incrementally and
+ * invalidates the sorted-name cache.
+ *
+ * @param module - The command module to register
+ */
 export declare function registerCommand(module: ShellModule): void;
+/**
+ * Creates a custom user-defined command from a shell script or function.
+ * The returned module is not automatically registered; call
+ * {@link registerCommand} to add it to the registry.
+ *
+ * @param name - The command name
+ * @param params - Parameter names for the command
+ * @param run   - The handler invoked when the command is executed
+ * @returns A command module that can be passed to registerCommand
+ */
 export declare function createCustomCommand(name: string, params: string[], run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>): ShellModule;
+/**
+ * Returns a sorted list of all registered command names (including aliases).
+ * The list is cached and rebuilt lazily when commands are added or removed.
+ *
+ * @returns A sorted array of command names
+ */
 export declare function getCommandNames(): string[];
+/**
+ * Returns all public command modules — built-in commands, custom commands,
+ * and the dynamically generated help command.
+ *
+ * @returns An array of all registered command modules
+ */
 export declare function getCommandModulesPublic(): ShellModule[];
+/**
+ * Resolves a command module by name or alias. The lookup is case-insensitive.
+ * Builds the internal cache first if it has not been populated yet.
+ *
+ * @param name - The command or alias name to look up
+ * @returns The matching ShellModule, or undefined if not found
+ */
 export declare function resolveModule(name: string): ShellModule | undefined;

package/dist/commands/registry.js

@@ -13,7 +13,9 @@ import { straceCommand } from "./strace";
 import { unzipCommand, zipCommand } from "./zip";
 import { catCommand } from "./cat";
 import { cdCommand } from "./cd";
+import { chgrpCommand } from "./chgrp";
 import { chmodCommand } from "./chmod";
+import { chownCommand } from "./chown";
 import { clearCommand } from "./clear";
 import { cpCommand } from "./cp";
 import { curlCommand } from "./curl";
@@ -97,6 +99,16 @@ import { whichCommand } from "./which";
 import { whoCommand } from "./who";
 import { whoamiCommand } from "./whoami";
 import { xargsCommand } from "./xargs";
+import { ddCommand } from "./dd";
+import { exprCommand } from "./expr";
+import { realpathCommand, md5sumCommand, sha256sumCommand, stringsCommand, foldCommand, expandCommand, fmtCommand } from "./miscutils";
+import { ncCommand } from "./netcat";
+import { niceCommand } from "./nice";
+import { nohupCommand } from "./nohup";
+import { pgrepCommand, pkillCommand } from "./procUtils";
+import { lscpuCommand, lsusbCommand, lspciCommand } from "./sysinfo";
+import { joinCommand, commCommand, splitCommand, csplitCommand } from "./textutils";
+import { topCommand } from "./top";
 const BASE_COMMANDS = [
     // Navigation
     pwdCommand,
@@ -113,9 +125,13 @@ const BASE_COMMANDS = [
     lnCommand,
     readlinkCommand,
     chmodCommand,
+    chownCommand,
+    chgrpCommand,
     seqCommand,
     statCommand,
     findCommand,
+    ddCommand,
+    realpathCommand,
     // Text processing
     grepCommand,
     sedCommand,
@@ -130,6 +146,16 @@ const BASE_COMMANDS = [
     teeCommand,
     xargsCommand,
     diffCommand,
+    foldCommand,
+    expandCommand,
+    fmtCommand,
+    md5sumCommand,
+    sha256sumCommand,
+    stringsCommand,
+    joinCommand,
+    commCommand,
+    splitCommand,
+    csplitCommand,
     // Archives
     tarCommand,
     gzipCommand,
@@ -153,6 +179,14 @@ const BASE_COMMANDS = [
     dateCommand,
     sleepCommand,
     pingCommand,
+    lscpuCommand,
+    lsusbCommand,
+    lspciCommand,
+    pgrepCommand,
+    pkillCommand,
+    topCommand,
+    niceCommand,
+    nohupCommand,
     // Shell
     echoCommand,
     envCommand,
@@ -184,6 +218,7 @@ const BASE_COMMANDS = [
     // Network
     curlCommand,
     wgetCommand,
+    ncCommand,
     // Users
     adduserCommand,
     passwdCommand,
@@ -222,6 +257,7 @@ const BASE_COMMANDS = [
     npxCommand,
     nodeCommand,
     python3Command,
+    exprCommand,
     // System (extended)
     uptimeCommand,
     freeCommand,
@@ -257,6 +293,14 @@ function buildCache() {
 function getCommandModules() {
     return [...BASE_COMMANDS, ...customCommands, helpCommand];
 }
+/**
+ * Registers a command module so it can be called from the shell.
+ * The module's name and aliases are lowercased and trimmed; names must be
+ * non-empty and contain no spaces. Updates the registry incrementally and
+ * invalidates the sorted-name cache.
+ *
+ * @param module - The command module to register
+ */
 export function registerCommand(module) {
     const normalized = {
         ...module,
@@ -275,17 +319,46 @@ export function registerCommand(module) {
     // Invalidate sorted names cache; rebuilt lazily on next getCommandNames()
     cachedCommandNames = null;
 }
+/**
+ * Creates a custom user-defined command from a shell script or function.
+ * The returned module is not automatically registered; call
+ * {@link registerCommand} to add it to the registry.
+ *
+ * @param name - The command name
+ * @param params - Parameter names for the command
+ * @param run   - The handler invoked when the command is executed
+ * @returns A command module that can be passed to registerCommand
+ */
 export function createCustomCommand(name, params, run) {
     return { name, params, run };
 }
+/**
+ * Returns a sorted list of all registered command names (including aliases).
+ * The list is cached and rebuilt lazily when commands are added or removed.
+ *
+ * @returns A sorted array of command names
+ */
 export function getCommandNames() {
     if (!cachedCommandNames)
         buildCache();
     return cachedCommandNames;
 }
+/**
+ * Returns all public command modules — built-in commands, custom commands,
+ * and the dynamically generated help command.
+ *
+ * @returns An array of all registered command modules
+ */
 export function getCommandModulesPublic() {
     return getCommandModules();
 }
+/**
+ * Resolves a command module by name or alias. The lookup is case-insensitive.
+ * Builds the internal cache first if it has not been populated yet.
+ *
+ * @param name - The command or alias name to look up
+ * @returns The matching ShellModule, or undefined if not found
+ */
 export function resolveModule(name) {
     if (!cachedCommandNames)
         buildCache();

package/dist/commands/rm.js

@@ -1,5 +1,6 @@
+import * as path from "node:path";
 import { getArg, ifFlag } from "./command-helpers";
-import { assertPathAccess, resolvePath } from "./helpers";
+import { checkFilePermission, resolvePath } from "./helpers";
 const FLAG_RECURSIVE = ["-r", "-R", "-rf", "-fr", "-rF", "-Fr"];
 const FLAG_FORCE = ["-f", "-rf", "-fr", "-rF", "-Fr", "--force"];
 /**
@@ -31,7 +32,7 @@ export const rmCommand = {
         }
         const resolved = targets.map((t) => resolvePath(cwd, t));
         for (const r of resolved)
-            assertPathAccess(authUser, r, "rm");
+            checkFilePermission(shell.vfs, shell.users, authUser, path.posix.dirname(r), 2);
         for (const r of resolved) {
             if (!shell.vfs.exists(r)) {
                 if (force)

package/dist/commands/runtime.d.ts

@@ -7,6 +7,52 @@ export declare function userHome(authUser: string): string;
  * the new user's .bashrc. Call this after setting authUser = newUser.
  */
 export declare function applyUserSwitch(newUser: string, hostname: string, cwd: string, shellEnv: ShellEnv, shell: VirtualShell): Promise<void>;
+/**
+ * Creates the default shell environment variables for a given user and host.
+ * Sets PATH, HOME, USER, LOGNAME, SHELL, TERM, HOSTNAME, and a coloured PS1
+ * prompt that distinguishes root (red) from ordinary users (magenta).
+ *
+ * @param authUser - The authenticated username
+ * @param hostname - The machine hostname
+ * @returns A ShellEnv populated with default variable values
+ */
 export declare function makeDefaultEnv(authUser: string, hostname: string): ShellEnv;
-export declare function runCommandDirect(name: string, args: string[], authUser: string, hostname: string, mode: CommandMode, cwd: string, shell: VirtualShell, stdin: string | undefined, env: ShellEnv): Promise<CommandResult>;
+/**
+ * Runs a command directly by name, bypassing shell parsing and expansion.
+ * Handles variable assignments prefixing the command, shell functions
+ * (stored as `__func_<name>`), aliases, registered modules, and VFS
+ * stub binaries. Includes an anti-loop guard via a module-level call depth
+ * counter and registers the process in the user's session table.
+ *
+ * @param name            - The command name to execute
+ * @param args            - Argument array (does not include the command name)
+ * @param authUser        - The authenticated user
+ * @param hostname        - The machine hostname
+ * @param mode            - The current command mode (shell, pipe, etc.)
+ * @param cwd             - The current working directory
+ * @param shell           - The VirtualShell instance
+ * @param stdin           - Optional stdin string
+ * @param env             - The current shell environment
+ * @param background      - Whether the command is run in the background
+ * @param abortController - Optional controller to abort a background process
+ * @returns The command result
+ */
+export declare function runCommandDirect(name: string, args: string[], authUser: string, hostname: string, mode: CommandMode, cwd: string, shell: VirtualShell, stdin: string | undefined, env: ShellEnv, background?: boolean, abortController?: AbortController): Promise<CommandResult>;
+/**
+ * Parses and runs a command line string through the full execution pipeline:
+ * history expansion (`!!` / `!n`), alias expansion, sh-syntax detection
+ * (for/while/if/function/arithmetic), pipe/redirect routing via the shell
+ * parser, variable expansion, brace expansion, and glob expansion. Falls
+ * back to the `sh` interpreter for compound constructs.
+ *
+ * @param rawInput - The raw command line string to parse and run
+ * @param authUser - The authenticated user
+ * @param hostname - The machine hostname
+ * @param mode     - The current command mode (shell, pipe, etc.)
+ * @param cwd      - The current working directory
+ * @param shell    - The VirtualShell instance
+ * @param stdin    - Optional stdin string
+ * @param env      - Optional shell environment (created from defaults if omitted)
+ * @returns The command result
+ */
 export declare function runCommand(rawInput: string, authUser: string, hostname: string, mode: CommandMode, cwd: string, shell: VirtualShell, stdin?: string, env?: ShellEnv): Promise<CommandResult>;