typescript-virtual-container 1.4.7 → 1.4.9

package/src/VirtualShell/index.ts

@@ -14,6 +14,7 @@ import { createPerfLogger } from "../utils/perfLogger";
 import VirtualFileSystem, { type VfsOptions } from "../VirtualFileSystem";
 import { VirtualPackageManager } from "../VirtualPackageManager";
 import { VirtualUserManager } from "../VirtualUserManager";
+import { IdleManager, type IdleManagerOptions } from "./idleManager";
 import { startShell } from "./shell";
 
 /**
@@ -41,6 +42,10 @@ export interface ShellProperties {
 	arch: string;
 }
 
+/**
+ * Minimal VFS interface accepted by {@link VirtualShell} as a drop-in replacement
+ * for the built-in {@link VirtualFileSystem}.
+ */
 export interface VirtualShellVfsLike {
 	restoreMirror(): Promise<void>;
 	flushMirror(): Promise<void>;
@@ -56,6 +61,9 @@ export interface VirtualShellVfsLike {
 	getUsageBytes?(targetPath?: string): number;
 }
 
+/**
+ * Constructor options for {@link VirtualShell} when passing an existing VFS instance.
+ */
 export interface VirtualShellVfsOptions {
 	vfsInstance?: VirtualShellVfsLike;
 }
@@ -143,6 +151,8 @@ class VirtualShell extends EventEmitter {
 	properties: ShellProperties;
 	/** Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. */
 	startTime: number;
+	/** Idle / cold-start manager — null until `enableIdleManagement()` is called. */
+	private _idle: IdleManager | null = null;
 	private initialized: Promise<void>;
 
 	/**
@@ -150,7 +160,7 @@ class VirtualShell extends EventEmitter {
 	 *
 	 * @param hostname Virtual hostname used for prompts and idents.
 	 * @param properties Customizable properties shown in `uname -a` and similar commands.
-	 * @param vfsOptions Optional VFS persistence options (mode, snapshotPath).
+	 * @param vfsOptionsOrInstance Optional VFS persistence options (mode, snapshotPath) or an existing VFS instance.
 	 */
 	constructor(
 		hostname: string,
@@ -236,6 +246,7 @@ class VirtualShell extends EventEmitter {
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		perf.mark("executeCommand");
+		this._idle?.ping();
 		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
 		this.emit("command", { command: rawInput, user: authUser, cwd });
 	}
@@ -262,6 +273,7 @@ class VirtualShell extends EventEmitter {
 		terminalSize: { cols: number; rows: number },
 	): void {
 		perf.mark("startInteractiveSession");
+		this._idle?.ping();
 		// Interactive shell logic
 		this.emit("session:start", { user: authUser, sessionId, remoteAddress });
 		startShell(
@@ -404,6 +416,57 @@ class VirtualShell extends EventEmitter {
 		this.users.assertWriteWithinQuota(authUser, targetPath, content);
 		this.vfs.writeFile(targetPath, content);
 	}
+
+	/**
+	 * Enable idle detection and cold-start freeze/thaw for this shell.
+	 *
+	 * After `idleThresholdMs` of inactivity the VFS tree is serialised and
+	 * released from RAM. The next command transparently restores it in ~0.1 ms.
+	 *
+	 * @example
+	 * ```ts
+	 * await shell.ensureInitialized();
+	 * shell.enableIdleManagement({ idleThresholdMs: 60_000 });
+	 * ```
+	 */
+	public enableIdleManagement(options?: IdleManagerOptions): void {
+		if (this._idle) return; // already enabled
+		this._idle = new IdleManager(this.vfs, options);
+		this._idle.on("freeze", () => this.emit("shell:freeze"));
+		this._idle.on("thaw",   () => this.emit("shell:thaw"));
+		this._idle.start();
+	}
+
+	/**
+	 * Disable idle management and thaw the shell if currently frozen.
+	 * Safe to call even if idle management was never enabled.
+	 */
+	public async disableIdleManagement(): Promise<void> {
+		if (!this._idle) return;
+		await this._idle.stop();
+		this._idle = null;
+	}
+
+	/**
+	 * Current idle state — `"active"` or `"frozen"`.
+	 * Returns `"active"` when idle management is disabled.
+	 */
+	public get idleState(): "active" | "frozen" {
+		return this._idle?.state ?? "active";
+	}
+
+	/** Milliseconds since last shell activity. 0 when idle management is disabled. */
+	public get idleMs(): number {
+		return this._idle?.idleMs ?? 0;
+	}
+
+	/**
+	 * Ping the idle manager to signal external activity (e.g. SFTP, direct VFS writes).
+	 * No-op when idle management is disabled.
+	 */
+	public pingIdle(): void {
+		this._idle?.ping();
+	}
 }
 
 export { VirtualShell };

package/src/VirtualUserManager/index.ts

@@ -5,7 +5,10 @@ import type { PerfLogger } from "../utils/perfLogger";
 import { createPerfLogger } from "../utils/perfLogger";
 import type VirtualFileSystem from "../VirtualFileSystem";
 
-/** Persisted virtual user credential record. */
+/** 
+ * Persisted virtual user credential record.
+ * @internal
+ */
 export interface VirtualUserRecord {
 	/** Unique login name. */
 	username: string;
@@ -61,7 +64,6 @@ export class VirtualUserManager extends EventEmitter {
 	 * Creates a user manager instance backed by a virtual filesystem.
 	 *
 	 * @param vfs Backing virtual filesystem used for persistence.
-	 * @param defaultRootPassword Initial root password used when root is created.
 	 * @param autoSudoForNewUsers Whether newly created users are added to sudoers.
 	 */
 	constructor(

package/src/commands/command-helpers.ts

@@ -1,4 +1,8 @@
-type ArgParseOptions = {
+/**
+ * Options for argument parsing helpers.
+ * @public
+ */
+export type ArgParseOptions = {
 	flags?: string[];
 	flagsWithValue?: string[];
 };

package/src/commands/man.ts

@@ -1,45 +1,10 @@
 import type { ShellModule } from "../types/commands";
+import { MANUALS } from "./manuals-bundle";
 
 const MANUAL_ALIASES: Record<string, string> = {
 	gunzip: "gzip",
 };
 
-const __dirname = import.meta.dirname;
-
-const manualCache = new Map<string, string | null>();
-const manualsBaseUrl = new URL("./manuals/", import.meta.url);
-
-async function dynamicImport(specifier: string): Promise<unknown> {
-	const importer = new Function(
-		"moduleName",
-		"return import(moduleName)",
-	) as (moduleName: string) => Promise<unknown>;
-	return importer(specifier);
-}
-
-async function loadBundledManual(commandName: string): Promise<string | null> {
-	const normalized = commandName.toLowerCase();
-	const lookupName = MANUAL_ALIASES[normalized] ?? normalized;
-	const cacheKey = `builtin:${lookupName}`;
-	if (manualCache.has(cacheKey)) {
-		return manualCache.get(cacheKey) ?? null;
-	}
-
-	try {
-		const fsModule = (await dynamicImport("node:fs/promises")) as {
-			readFile: (path: URL, encoding: "utf8") => Promise<string>;
-		};
-		const manualUrl = new URL(`${lookupName}.txt`, manualsBaseUrl);
-		const content = await fsModule.readFile(manualUrl, "utf8");
-		const page = content.replace(/\n$/, "");
-		manualCache.set(cacheKey, page);
-		return page;
-	} catch {
-		manualCache.set(cacheKey, null);
-		return null;
-	}
-}
-
 export const manCommand: ShellModule = {
 	name: "man",
 	description: "Interface to the system reference manuals",
@@ -55,7 +20,10 @@ export const manCommand: ShellModule = {
 			return { stdout: shell.vfs.readFile(manPath), exitCode: 0 };
 		}
 
-		const page = await loadBundledManual(name);
+		// Bundled manuals — available in all build modes (standalone, web, dev)
+		const normalized = name.toLowerCase();
+		const lookupName = MANUAL_ALIASES[normalized] ?? normalized;
+		const page = MANUALS[lookupName] ?? null;
 		if (page) return { stdout: page, exitCode: 0 };
 
 		return { stderr: `No manual entry for ${name}`, exitCode: 16 };