typescript-virtual-container 1.4.6 → 1.4.8

package/src/VirtualFileSystem/internalTypes.ts

@@ -1,19 +1,39 @@
-export type InternalNode = InternalFileNode | InternalDirectoryNode;
+export type InternalNode = InternalFileNode | InternalStubNode | InternalDirectoryNode;
 
 interface InternalBaseNode {
 	name: string;
 	mode: number;
-	createdAt: Date;
-	updatedAt: Date;
+	/** Unix timestamp in ms — avoids Date object overhead (~80 bytes each). */
+	createdAt: number;
+	/** Unix timestamp in ms. */
+	updatedAt: number;
 }
 
 export interface InternalFileNode extends InternalBaseNode {
 	type: "file";
 	content: Buffer;
 	compressed: boolean;
+	/** When true, content has been purged from RAM. Reloaded from snapshot on demand. */
+	evicted?: true;
+	/** Byte length of the original (uncompressed) content — preserved when evicted. */
+	size?: number;
+}
+
+/**
+ * Lazy stub — stores static rootfs file content as a plain string.
+ * No Buffer allocation until the file is actually read or written.
+ * On first write, promoted to a real InternalFileNode.
+ */
+export interface InternalStubNode extends InternalBaseNode {
+	type: "stub";
+	/** Raw UTF-8 content — never compressed, never evicted. */
+	stubContent: string;
 }
 
 export interface InternalDirectoryNode extends InternalBaseNode {
 	type: "directory";
-	children: Map<string, InternalNode>;
+	/** Null-prototype object — avoids Map overhead (~40% less RAM per entry). */
+	children: Record<string, InternalNode>;
+	/** Cached child count — avoids O(n) Object.keys() on hot paths. */
+	_childCount: number;
 }

package/src/VirtualFileSystem/journal.ts

@@ -0,0 +1,163 @@
+/**
+ * journal.ts — Write-Ahead Log for VirtualFileSystem "fs" mode.
+ *
+ * Each mutating VFS operation is appended to `vfs-journal.bin` immediately.
+ * On `restoreMirror()` the base snapshot is loaded first, then the journal
+ * is replayed on top. On `flushMirror()` a new checkpoint is written and
+ * the journal is truncated.
+ *
+ * Entry format (binary, little-endian):
+ *   [1B op] [2B path_len] [path bytes] [payload per op]
+ *
+ * Op codes:
+ *   0x01 WRITE  — [4B content_len] [content bytes] [4B mode]
+ *   0x02 MKDIR  — [4B mode]
+ *   0x03 REMOVE — (no payload)
+ *   0x04 CHMOD  — [4B mode]
+ *   0x05 MOVE   — [2B dest_len] [dest bytes]
+ *   0x06 SYMLINK — [2B target_len] [target bytes]
+ */
+/** biome-ignore-all lint/style/useNamingConvention: JournalOp modes */
+
+import * as fsSync from "node:fs";
+
+export const JournalOp = {
+	WRITE:   0x01,
+	MKDIR:   0x02,
+	REMOVE:  0x03,
+	CHMOD:   0x04,
+	MOVE:    0x05,
+	SYMLINK: 0x06,
+} as const;
+
+export type JournalOp = typeof JournalOp[keyof typeof JournalOp];
+
+export interface JournalEntry {
+	op:      JournalOp;
+	path:    string;
+	content?: Buffer;
+	mode?:   number;
+	dest?:   string;   // MOVE destination, SYMLINK target
+}
+
+const ENC = "utf8" as const;
+
+function writeString2(buf: Buffer, offset: number, s: string): number {
+	const b = Buffer.from(s, ENC);
+	buf.writeUInt16LE(b.length, offset);
+	b.copy(buf, offset + 2);
+	return 2 + b.length;
+}
+
+/** Serialise one entry to a Buffer. */
+export function encodeEntry(e: JournalEntry): Buffer {
+	const pathBuf = Buffer.from(e.path, ENC);
+	let payloadLen = 0;
+
+	if (e.op === JournalOp.WRITE) {
+		payloadLen = 4 + (e.content?.length ?? 0) + 4;
+	} else if (e.op === JournalOp.MKDIR) {
+		payloadLen = 4;
+	} else if (e.op === JournalOp.REMOVE) {
+		payloadLen = 0;
+	} else if (e.op === JournalOp.CHMOD) {
+		payloadLen = 4;
+	} else if (e.op === JournalOp.MOVE || e.op === JournalOp.SYMLINK) {
+		payloadLen = 2 + Buffer.byteLength(e.dest ?? "", ENC);
+	}
+
+	const total = 1 + 2 + pathBuf.length + payloadLen;
+	const buf   = Buffer.allocUnsafe(total);
+	let off = 0;
+
+	buf.writeUInt8(e.op, off++);
+	buf.writeUInt16LE(pathBuf.length, off); off += 2;
+	pathBuf.copy(buf, off); off += pathBuf.length;
+
+	if (e.op === JournalOp.WRITE) {
+		const c = e.content ?? Buffer.alloc(0);
+		buf.writeUInt32LE(c.length, off); off += 4;
+		c.copy(buf, off); off += c.length;
+		buf.writeUInt32LE(e.mode ?? 0o644, off); off += 4;
+	} else if (e.op === JournalOp.MKDIR) {
+		buf.writeUInt32LE(e.mode ?? 0o755, off); off += 4;
+	} else if (e.op === JournalOp.CHMOD) {
+		buf.writeUInt32LE(e.mode ?? 0o644, off); off += 4;
+	} else if (e.op === JournalOp.MOVE || e.op === JournalOp.SYMLINK) {
+		off += writeString2(buf, off, e.dest ?? "");
+	}
+
+	return buf;
+}
+
+/** Parse all entries from a journal Buffer. Returns empty array on corrupt data. */
+export function decodeJournal(buf: Buffer): JournalEntry[] {
+	const entries: JournalEntry[] = [];
+	let off = 0;
+
+	try {
+		while (off < buf.length) {
+			if (off + 3 > buf.length) break;
+			const op      = buf.readUInt8(off++) as JournalOp;
+			const pathLen = buf.readUInt16LE(off); off += 2;
+			if (off + pathLen > buf.length) break;
+			const path    = buf.subarray(off, off + pathLen).toString(ENC); off += pathLen;
+
+			if (op === JournalOp.WRITE) {
+				if (off + 4 > buf.length) break;
+				const cLen = buf.readUInt32LE(off); off += 4;
+				if (off + cLen + 4 > buf.length) break;
+				const content = Buffer.from(buf.subarray(off, off + cLen)); off += cLen;
+				const mode    = buf.readUInt32LE(off); off += 4;
+				entries.push({ op, path, content, mode });
+			} else if (op === JournalOp.MKDIR) {
+				if (off + 4 > buf.length) break;
+				const mode = buf.readUInt32LE(off); off += 4;
+				entries.push({ op, path, mode });
+			} else if (op === JournalOp.REMOVE) {
+				entries.push({ op, path });
+			} else if (op === JournalOp.CHMOD) {
+				if (off + 4 > buf.length) break;
+				const mode = buf.readUInt32LE(off); off += 4;
+				entries.push({ op, path, mode });
+			} else if (op === JournalOp.MOVE || op === JournalOp.SYMLINK) {
+				if (off + 2 > buf.length) break;
+				const dLen = buf.readUInt16LE(off); off += 2;
+				if (off + dLen > buf.length) break;
+				const dest = buf.subarray(off, off + dLen).toString(ENC); off += dLen;
+				entries.push({ op, path, dest });
+			} else {
+				// Unknown op — skip rest of buffer to avoid corrupt replay
+				break;
+			}
+		}
+	} catch {
+		// Truncated or corrupt entry — return what we have
+	}
+
+	return entries;
+}
+
+/** Append a single entry to the journal file (O_APPEND, atomic write). */
+export function appendJournalEntry(journalPath: string, entry: JournalEntry): void {
+	const buf = encodeEntry(entry);
+	const fd  = fsSync.openSync(journalPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_APPEND);
+	try {
+		fsSync.writeSync(fd, buf);
+	} finally {
+		fsSync.closeSync(fd);
+	}
+}
+
+/** Read and decode all entries from a journal file. Returns [] if file is absent/empty. */
+export function readJournal(journalPath: string): JournalEntry[] {
+	if (!fsSync.existsSync(journalPath)) return [];
+	const buf = fsSync.readFileSync(journalPath);
+	if (buf.length === 0) return [];
+	return decodeJournal(buf);
+}
+
+/** Delete the journal file (after a successful checkpoint). */
+export function truncateJournal(journalPath: string): void {
+	if (fsSync.existsSync(journalPath)) fsSync.unlinkSync(journalPath);
+}

package/src/VirtualFileSystem/path.ts

@@ -33,7 +33,7 @@ export function getNode(
 			throw new Error(`Path '${normalized}' does not exist.`);
 		}
 
-		const next = current.children.get(part);
+		const next: InternalNode | undefined = current.children[part];
 		if (!next) {
 			throw new Error(`Path '${normalized}' does not exist.`);
 		}

package/src/VirtualShell/idleManager.ts

@@ -0,0 +1,133 @@
+/**
+ * IdleManager — cold-start / freeze-thaw system for VirtualShell.
+ *
+ * When a shell has had no activity for `idleThresholdMs`, the VFS tree is
+ * serialised to a compact binary buffer and the in-memory tree is released.
+ * On the next command the tree is reconstructed in ~0.1 ms.
+ *
+ * Memory freed per idle shell: the full JS object graph (~250+ InternalNodes
+ * for a typical rootfs + user files). The frozen buffer itself stays in RAM
+ * but is ~27% smaller than the live tree and GC-friendly (one flat Buffer).
+ *
+ * CPU freed: the VFS auto-flush setInterval is suspended while frozen.
+ *
+ * Usage:
+ * ```ts
+ * const idle = new IdleManager(shell, { idleThresholdMs: 60_000 });
+ * idle.start();
+ * // call idle.ping() on every shell activity (exec, keypress, …)
+ * // call idle.stop() on shell destroy
+ * ```
+ */
+
+import { EventEmitter } from "node:events";
+import type VirtualFileSystem from "../VirtualFileSystem";
+import { decodeVfs } from "../VirtualFileSystem/binaryPack";
+
+export interface IdleManagerOptions {
+	/**
+	 * Milliseconds of inactivity before the shell is frozen.
+	 * Default: 60_000 (1 minute).
+	 */
+	idleThresholdMs?: number;
+	/**
+	 * How often the idle check runs.
+	 * Default: 15_000 (15 seconds).
+	 */
+	checkIntervalMs?: number;
+}
+
+export type IdleState = "active" | "frozen";
+
+export class IdleManager extends EventEmitter {
+	private readonly vfs: VirtualFileSystem;
+	private readonly idleThresholdMs: number;
+	private readonly checkIntervalMs: number;
+
+	private _state: IdleState = "active";
+	private _lastActivity = Date.now();
+	private _frozenBuffer: Buffer | null = null;
+	private _checkTimer: ReturnType<typeof setInterval> | null = null;
+
+	/** Emitted when the shell is frozen (VFS tree released). */
+	declare on: ((event: "freeze", listener: () => void) => this) &
+		((event: "thaw", listener: () => void) => this) &
+		((event: string, listener: (...args: unknown[]) => void) => this);
+
+	constructor(vfs: VirtualFileSystem, options: IdleManagerOptions = {}) {
+		super();
+		this.vfs = vfs;
+		this.idleThresholdMs = options.idleThresholdMs ?? 60_000;
+		this.checkIntervalMs = options.checkIntervalMs ?? 15_000;
+	}
+
+	/** Start monitoring for idle. Call once after shell initialisation. */
+	public start(): void {
+		if (this._checkTimer) return;
+		this._lastActivity = Date.now();
+		this._checkTimer = setInterval(() => this._check(), this.checkIntervalMs);
+		// Don't block process exit
+		if (typeof this._checkTimer === "object" && this._checkTimer !== null && "unref" in this._checkTimer) {
+			(this._checkTimer as NodeJS.Timeout).unref();
+		}
+	}
+
+	/** Stop monitoring and thaw if frozen. Call on shell destroy. */
+	public async stop(): Promise<void> {
+		if (this._checkTimer) {
+			clearInterval(this._checkTimer);
+			this._checkTimer = null;
+		}
+		if (this._state === "frozen") await this._thaw();
+	}
+
+	/**
+	 * Signal activity — resets the idle clock and thaws if frozen.
+	 * Call this before every exec / keypress / session event.
+	 */
+	public async ping(): Promise<void> {
+		this._lastActivity = Date.now();
+		if (this._state === "frozen") await this._thaw();
+	}
+
+	/** Current idle state. */
+	public get state(): IdleState {
+		return this._state;
+	}
+
+	/** Ms since last activity. */
+	public get idleMs(): number {
+		return Date.now() - this._lastActivity;
+	}
+
+	// ── Internal ──────────────────────────────────────────────────────────────
+
+	private _check(): void {
+		if (this._state === "frozen") return; // already frozen
+		if (Date.now() - this._lastActivity >= this.idleThresholdMs) {
+			void this._freeze();
+		}
+	}
+
+	private async _freeze(): Promise<void> {
+		if (this._state === "frozen") return;
+		// Flush any pending writes before freezing
+		await this.vfs.stopAutoFlush();
+		// Serialise the live tree to a compact binary buffer
+		this._frozenBuffer = this.vfs.encodeBinary();
+		// Release the live tree — GC can now collect all InternalNode objects
+		this.vfs.releaseTree();
+		this._state = "frozen";
+		this.emit("freeze");
+	}
+
+	private async _thaw(): Promise<void> {
+		if (this._state !== "frozen" || !this._frozenBuffer) return;
+		// Reconstruct the tree from the frozen buffer (~0.07 ms for typical rootfs)
+		const root = decodeVfs(this._frozenBuffer);
+		this.vfs.importRootTree(root);
+		this._frozenBuffer = null;
+		this._state = "active";
+		this.emit("thaw");
+	}
+}

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";
 
 /**
@@ -143,6 +144,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>;
 
 	/**
@@ -236,6 +239,7 @@ class VirtualShell extends EventEmitter {
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		perf.mark("executeCommand");
+		if (this._idle) void this._idle.ping();
 		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
 		this.emit("command", { command: rawInput, user: authUser, cwd });
 	}
@@ -262,6 +266,7 @@ class VirtualShell extends EventEmitter {
 		terminalSize: { cols: number; rows: number },
 	): void {
 		perf.mark("startInteractiveSession");
+		if (this._idle) void this._idle.ping();
 		// Interactive shell logic
 		this.emit("session:start", { user: authUser, sessionId, remoteAddress });
 		startShell(
@@ -404,6 +409,49 @@ 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;
+	}
 }
 
 export { VirtualShell };

package/src/VirtualShell/shell.ts

@@ -202,7 +202,7 @@ export function startShell(
 			cwd = result.nextCwd;
 		}
 
-		await shell.vfs.flushMirror();
+		// WAL: checkpoint handled by auto-flush timer
 		renderLine();
 	}
 
@@ -221,7 +221,7 @@ export function startShell(
 					activeSession.targetPath,
 					updatedContent,
 				);
-				await shell.vfs.flushMirror();
+				// WAL: checkpoint handled by auto-flush timer
 			} catch {
 				// If temp file does not exist, nano exited without writing.
 			}
@@ -498,7 +498,7 @@ export function startShell(
 				historyDraft = "";
 				stream.write("bye\r\n");
 				pushHistory("bye");
-				await shell.vfs.flushMirror();
+				// WAL: checkpoint handled by auto-flush timer
 				stream.write("logout\r\n");
 				stream.exit(0);
 				stream.end();
@@ -657,7 +657,7 @@ export function startShell(
 						cursorPos = 0;
 					}
 
-					await shell.vfs.flushMirror();
+					// WAL: checkpoint handled by auto-flush timer
 				}
 
 				renderLine();

package/src/commands/man.ts

@@ -1,43 +1,10 @@
 import type { ShellModule } from "../types/commands";
+import { MANUALS } from "./manuals-bundle";
 
 const MANUAL_ALIASES: Record<string, string> = {
 	gunzip: "gzip",
 };
 
-const manualCache = new Map<string, string | null>();
-const manualsBaseUrl = `${__dirname}/manuals/`;
-
-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",
@@ -53,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 };