typescript-virtual-container 1.5.10 → 1.6.0

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,12 +4,13 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.5.10",
+  "version": "1.6.0",
   "files": [
     "dist/",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "scripts/postinstall.js"
   ],
   "license": "MIT",
   "repository": {

package/scripts/postinstall.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+function deleteFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+    console.log(`Deleted: ${filePath}`);
+  }
+}
+
+function deleteDirectory(dirPath) {
+  if (fs.existsSync(dirPath)) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+    console.log(`Deleted: ${dirPath}`);
+  }
+}
+
+const sshCryptoPath = path.join(
+  __dirname,
+  '..',
+  'node_modules',
+  'ssh2',
+  'lib',
+  'protocol',
+  'crypto',
+  'build',
+  'Release',
+  'sshcrypto.node'
+);
+
+const cpuFeaturesPath = path.join(
+  __dirname,
+  '..',
+  'node_modules',
+  'cpu-features'
+);
+
+deleteFile(sshCryptoPath);
+deleteDirectory(cpuFeaturesPath);