typescript-virtual-container 1.5.11 → 1.6.1

package/dist/modules/pacmanGame.d.ts

@@ -1,10 +1,12 @@
 import type { ShellStream } from "../types/streams";
 import type { TerminalSize } from "./shellRuntime";
+/** Configuration options for creating a PacmanGame instance. */
 export interface PacmanGameOptions {
     stream: ShellStream;
     terminalSize: TerminalSize;
     onExit: () => void;
 }
+/** Classic Pacman game that runs in the terminal with ANSI rendering. */
 export declare class PacmanGame {
     private stream;
     private onExit;

package/dist/modules/pacmanGame.js

@@ -92,6 +92,7 @@ const DR = [0, 1, 0, -1];
 const DC = [1, 0, -1, 0];
 const OPP = [2, 3, 0, 1];
 // ── PacmanGame ────────────────────────────────────────────────────────────────
+/** Classic Pacman game that runs in the terminal with ANSI rendering. */
 export class PacmanGame {
     stream;
     onExit;

package/dist/modules/shellInteractive.d.ts

@@ -1,5 +1,7 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
 import type { ShellStream } from "../types/streams";
 import { type TerminalSize } from "./shellRuntime";
+/** Spawns the nano editor as an interactive subprocess. */
 export declare function spawnNanoEditorProcess(tempPath: string, terminalSize: TerminalSize, stream: ShellStream): ChildProcessWithoutNullStreams;
+/** Spawns htop as an interactive subprocess, filtered to the given PIDs. */
 export declare function spawnHtopProcess(pidList: string, terminalSize: TerminalSize, stream: ShellStream): ChildProcessWithoutNullStreams;

package/dist/modules/shellInteractive.js

@@ -18,9 +18,11 @@ function spawnScriptProcess(command, terminalSize, stream) {
     });
     return proc;
 }
+/** Spawns the nano editor as an interactive subprocess. */
 export function spawnNanoEditorProcess(tempPath, terminalSize, stream) {
     return spawnScriptProcess(`nano -- ${shellQuote(tempPath)}`, terminalSize, stream);
 }
+/** Spawns htop as an interactive subprocess, filtered to the given PIDs. */
 export function spawnHtopProcess(pidList, terminalSize, stream) {
     return spawnScriptProcess(`htop -p ${shellQuote(pidList)}`, terminalSize, stream);
 }

package/dist/modules/shellRuntime.d.ts

@@ -1,10 +1,17 @@
+/** Terminal dimensions (columns × rows). */
 export interface TerminalSize {
     cols: number;
     rows: number;
 }
+/** Shell-escapes a string for safe use in a command line. */
 export declare function shellQuote(value: string): string;
+/** Converts line endings to CRLF for TTY output. */
 export declare function toTtyLines(text: string): string;
+/** Wraps a command to run with a specific terminal size via stty. */
 export declare function withTerminalSize(command: string, terminalSize: TerminalSize): string;
+/** Resolves a path relative to a base working directory. */
 export declare function resolvePath(base: string, inputPath: string): string;
+/** Recursively collects all child PIDs of a given parent process. */
 export declare function collectChildPids(parentPid: number): Promise<number[]>;
+/** Returns a comma-separated PID list visible in htop, or null if none. */
 export declare function getVisibleHtopPidList(rootPid?: number): Promise<string | null>;

package/dist/modules/shellRuntime.js

@@ -1,14 +1,17 @@
 import { readFile } from "node:fs/promises";
 import * as path from "node:path";
+/** Shell-escapes a string for safe use in a command line. */
 export function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+/** Converts line endings to CRLF for TTY output. */
 export function toTtyLines(text) {
     return text
         .replace(/\r\n/g, "\n")
         .replace(/\r/g, "\n")
         .replace(/\n/g, "\r\n");
 }
+/** Wraps a command to run with a specific terminal size via stty. */
 export function withTerminalSize(command, terminalSize) {
     const cols = Number.isFinite(terminalSize.cols) && terminalSize.cols > 0
         ? Math.floor(terminalSize.cols)
@@ -18,6 +21,7 @@ export function withTerminalSize(command, terminalSize) {
         : 24;
     return `stty cols ${cols} rows ${rows} 2>/dev/null; ${command}`;
 }
+/** Resolves a path relative to a base working directory. */
 export function resolvePath(base, inputPath) {
     if (!inputPath || inputPath.trim() === "" || inputPath === ".") {
         return base;
@@ -26,6 +30,7 @@ export function resolvePath(base, inputPath) {
         ? path.posix.normalize(inputPath)
         : path.posix.normalize(path.posix.join(base, inputPath));
 }
+/** Recursively collects all child PIDs of a given parent process. */
 export async function collectChildPids(parentPid) {
     try {
         const childrenRaw = await readFile(`/proc/${parentPid}/task/${parentPid}/children`, "utf8");
@@ -42,6 +47,7 @@ export async function collectChildPids(parentPid) {
         return [];
     }
 }
+/** Returns a comma-separated PID list visible in htop, or null if none. */
 export async function getVisibleHtopPidList(rootPid = process.pid) {
     const descendants = await collectChildPids(rootPid);
     const unique = Array.from(new Set(descendants)).sort((a, b) => a - b);

package/dist/modules/webTermRenderer.js

@@ -392,13 +392,6 @@ export class WebTermRenderer {
         return html;
     }
 }
-// const ANSI_NORMAL_TO_BRIGHT: Record<string, string> = {
-// 	"#000": "#555", "#c00": "#f55", "#0c0": "#5f5", "#cc0": "#ff5",
-// 	"#00c": "#55f", "#c0c": "#f5f", "#0cc": "#5ff", "#ccc": "#fff",
-// };
-// function boldBright(fg: string): string {
-// 	return ANSI_NORMAL_TO_BRIGHT[fg] ?? fg;
-// }
 function escHtml(ch) {
     if (ch === "&")
         return "&amp;";

package/dist/types/commands.d.ts

@@ -1,5 +1,5 @@
 /** Command invocation mode used by shell runtime. */
-export type CommandMode = "shell" | "exec";
+export type CommandMode = "shell" | "exec" | "background";
 import type { VirtualShell } from "../VirtualShell";
 import type { VirtualActiveSession } from "../VirtualUserManager";
 /**

package/dist/types/vfs.d.ts

@@ -8,6 +8,10 @@ export interface VfsBaseNode {
     path: string;
     /** POSIX-like mode bits. */
     mode: number;
+    /** Owner user ID (0 = root). */
+    uid: number;
+    /** Owner group ID (0 = root). */
+    gid: number;
     /** Node creation timestamp. */
     createdAt: Date;
     /** Last update timestamp. */
@@ -45,6 +49,10 @@ export interface RemoveOptions {
 export interface VfsSnapshotBaseNode {
     name: string;
     mode: number;
+    /** Owner user ID (0 = root). */
+    uid: number;
+    /** Owner group ID (0 = root). */
+    gid: number;
     /** ISO-8601 creation timestamp. */
     createdAt: string;
     /** ISO-8601 update timestamp. */

package/dist/utils/argv.d.ts

@@ -1,6 +1,25 @@
-/** Returns true if `name` appears in `argv`. */
+/**
+ * Returns true if the given flag is present in the argv array.
+ * @param argv - The array of command-line arguments.
+ * @param name - The exact flag string to look for (e.g. `"--verbose"`).
+ * @returns `true` if the flag is present, `false` otherwise.
+ */
 export declare function getFlag(argv: string[], name: string): boolean;
-/** Returns the string value for `--name=VALUE` or `--name VALUE`, or `fallback`. */
+/**
+ * Gets the string value of an option from argv.
+ * Supports both `--name=VALUE` and `--name VALUE` forms.
+ * @param argv - The array of command-line arguments.
+ * @param name - The option name (e.g. `"--output"`).
+ * @param fallback - The default value if the option is not found.
+ * @returns The option value, or `fallback` if absent.
+ */
 export declare function getOptionString(argv: string[], name: string, fallback: string): string;
-/** Returns the integer value for `--name=VALUE` or `--name VALUE`, or `fallback`. */
+/**
+ * Gets the integer value of an option from argv.
+ * Supports both `--name=VALUE` and `--name VALUE` forms.
+ * @param argv - The array of command-line arguments.
+ * @param name - The option name (e.g. `"--port"`).
+ * @param fallback - The default value if the option is not found or cannot be parsed.
+ * @returns The parsed integer, or `fallback` if absent or unparseable.
+ */
 export declare function getOptionInt(argv: string[], name: string, fallback: number): number;

package/dist/utils/argv.js

@@ -1,8 +1,20 @@
-/** Returns true if `name` appears in `argv`. */
+/**
+ * Returns true if the given flag is present in the argv array.
+ * @param argv - The array of command-line arguments.
+ * @param name - The exact flag string to look for (e.g. `"--verbose"`).
+ * @returns `true` if the flag is present, `false` otherwise.
+ */
 export function getFlag(argv, name) {
     return argv.includes(name);
 }
-/** Returns the string value for `--name=VALUE` or `--name VALUE`, or `fallback`. */
+/**
+ * Gets the string value of an option from argv.
+ * Supports both `--name=VALUE` and `--name VALUE` forms.
+ * @param argv - The array of command-line arguments.
+ * @param name - The option name (e.g. `"--output"`).
+ * @param fallback - The default value if the option is not found.
+ * @returns The option value, or `fallback` if absent.
+ */
 export function getOptionString(argv, name, fallback) {
     const prefix = `${name}=`;
     for (let i = 0; i < argv.length; i++) {
@@ -16,7 +28,14 @@ export function getOptionString(argv, name, fallback) {
     }
     return fallback;
 }
-/** Returns the integer value for `--name=VALUE` or `--name VALUE`, or `fallback`. */
+/**
+ * Gets the integer value of an option from argv.
+ * Supports both `--name=VALUE` and `--name VALUE` forms.
+ * @param argv - The array of command-line arguments.
+ * @param name - The option name (e.g. `"--port"`).
+ * @param fallback - The default value if the option is not found or cannot be parsed.
+ * @returns The parsed integer, or `fallback` if absent or unparseable.
+ */
 export function getOptionInt(argv, name, fallback) {
     const prefix = `${name}=`;
     for (let i = 0; i < argv.length; i++) {

package/dist/utils/perfLogger.d.ts

@@ -1,8 +1,16 @@
+/**
+ * Interface for a performance logger instance.
+ * When `enabled` is false, `mark` and `done` are no-ops.
+ */
 export type PerfLogger = {
     enabled: boolean;
     mark: (label: string) => void;
     done: (label?: string) => void;
 };
-export declare function isPerfLoggingEnabled(): boolean;
+/**
+ * Creates a performance logger that logs elapsed-time marks to the console.
+ * Logging is only active when `DEV_MODE` or `RENDER_PERF` env vars are truthy.
+ * @param scope - A label prefixed to every log line (e.g. `"render"`).
+ * @returns A {@link PerfLogger} instance.
+ */
 export declare function createPerfLogger(scope: string): PerfLogger;
-export declare function withPerf<T>(scope: string, label: string, work: () => Promise<T>): Promise<T>;

package/dist/utils/perfLogger.js

@@ -8,9 +8,15 @@ function nowMs() {
     }
     return Date.now();
 }
-export function isPerfLoggingEnabled() {
+function isPerfLoggingEnabled() {
     return (isTruthyEnv(process.env.DEV_MODE) || isTruthyEnv(process.env.RENDER_PERF));
 }
+/**
+ * Creates a performance logger that logs elapsed-time marks to the console.
+ * Logging is only active when `DEV_MODE` or `RENDER_PERF` env vars are truthy.
+ * @param scope - A label prefixed to every log line (e.g. `"render"`).
+ * @returns A {@link PerfLogger} instance.
+ */
 export function createPerfLogger(scope) {
     const enabled = isPerfLoggingEnabled();
     if (!enabled) {
@@ -34,16 +40,3 @@ export function createPerfLogger(scope) {
         done,
     };
 }
-export async function withPerf(scope, label, work) {
-    const perf = createPerfLogger(scope);
-    if (!perf.enabled) {
-        return work();
-    }
-    perf.mark(`${label}:start`);
-    try {
-        return await work();
-    }
-    finally {
-        perf.done(`${label}:done`);
-    }
-}

package/dist/utils/shellSession.d.ts

@@ -1,10 +1,45 @@
 import type VirtualFileSystem from "../VirtualFileSystem";
+/**
+ * Loads the shell command history for a user from the VFS.
+ * Creates an empty history file if none exists.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @returns An array of history lines, with empty lines removed.
+ */
 export declare function loadHistory(vfs: VirtualFileSystem, authUser: string): string[];
+/**
+ * Saves shell command history for a user to the VFS.
+ * Each entry is written on its own line to `.bash_history`.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @param history - The ordered list of history entries to persist.
+ */
 export declare function saveHistory(vfs: VirtualFileSystem, authUser: string, history: string[]): void;
 export interface LastLogin {
     at: string;
     from: string;
 }
+/**
+ * Reads the last-login timestamp for a user from the VFS.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @returns The `LastLogin` object, or `null` if no record exists or parsing fails.
+ */
 export declare function readLastLogin(vfs: VirtualFileSystem, authUser: string): LastLogin | null;
+/**
+ * Writes the current timestamp as the last login for a user to the VFS.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @param from - An identifier for the origin of the login session (e.g. `"web"` or `"ssh"`).
+ */
 export declare function writeLastLogin(vfs: VirtualFileSystem, authUser: string, from: string): void;
+/**
+ * Lists path completions for tab-completion in the shell.
+ * Filters directory entries that match the given prefix, hides dot-files
+ * unless the prefix itself starts with a dot, and appends `"/"` to directories.
+ * @param vfs - The virtual file system instance.
+ * @param cwd - The current working directory to resolve relative paths against.
+ * @param prefix - The partial path to complete (e.g. `"/usr/lo"` or `"./fo"`).
+ * @returns A sorted array of matching completion candidates.
+ */
 export declare function listPathCompletions(vfs: VirtualFileSystem, cwd: string, prefix: string): string[];

package/dist/utils/shellSession.js

@@ -2,6 +2,13 @@ import * as path from "node:path";
 import { resolvePath } from "../commands/helpers";
 import { userHome } from "../commands/runtime";
 // ── History ───────────────────────────────────────────────────────────────────
+/**
+ * Loads the shell command history for a user from the VFS.
+ * Creates an empty history file if none exists.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @returns An array of history lines, with empty lines removed.
+ */
 export function loadHistory(vfs, authUser) {
     const historyPath = `${userHome(authUser)}/.bash_history`;
     if (!vfs.exists(historyPath)) {
@@ -13,10 +20,23 @@ export function loadHistory(vfs, authUser) {
         .map((l) => l.trim())
         .filter((l) => l.length > 0);
 }
+/**
+ * Saves shell command history for a user to the VFS.
+ * Each entry is written on its own line to `.bash_history`.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @param history - The ordered list of history entries to persist.
+ */
 export function saveHistory(vfs, authUser, history) {
     const data = history.length > 0 ? `${history.join("\n")}\n` : "";
     vfs.writeFile(`${userHome(authUser)}/.bash_history`, data);
 }
+/**
+ * Reads the last-login timestamp for a user from the VFS.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @returns The `LastLogin` object, or `null` if no record exists or parsing fails.
+ */
 export function readLastLogin(vfs, authUser) {
     const p = authUser === "root" ? "/root/.lastlog.json" : `/home/${authUser}/.lastlog`;
     if (!vfs.exists(p))
@@ -28,11 +48,26 @@ export function readLastLogin(vfs, authUser) {
         return null;
     }
 }
+/**
+ * Writes the current timestamp as the last login for a user to the VFS.
+ * @param vfs - The virtual file system instance.
+ * @param authUser - The authenticated username.
+ * @param from - An identifier for the origin of the login session (e.g. `"web"` or `"ssh"`).
+ */
 export function writeLastLogin(vfs, authUser, from) {
     const p = authUser === "root" ? "/root/.lastlog.json" : `/home/${authUser}/.lastlog`;
     vfs.writeFile(p, JSON.stringify({ at: new Date().toISOString(), from }));
 }
 // ── Path completion ───────────────────────────────────────────────────────────
+/**
+ * Lists path completions for tab-completion in the shell.
+ * Filters directory entries that match the given prefix, hides dot-files
+ * unless the prefix itself starts with a dot, and appends `"/"` to directories.
+ * @param vfs - The virtual file system instance.
+ * @param cwd - The current working directory to resolve relative paths against.
+ * @param prefix - The partial path to complete (e.g. `"/usr/lo"` or `"./fo"`).
+ * @returns A sorted array of matching completion candidates.
+ */
 export function listPathCompletions(vfs, cwd, prefix) {
     const slashIndex = prefix.lastIndexOf("/");
     const dirPart = slashIndex >= 0 ? prefix.slice(0, slashIndex + 1) : "";

package/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.5.11",
+  "version": "1.6.1",
   "files": [
     "dist/",
     "README.md",