typescript-virtual-container 0.1.0

package/src/VirtualFileSystem.ts

@@ -0,0 +1,420 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+import type {
+	RemoveOptions,
+	VfsNodeStats,
+	WriteFileOptions,
+} from "./types/vfs";
+import {
+	archiveExists,
+	createTarBuffer,
+	readSnapshotFromTar,
+} from "./vfs/archive";
+import type { InternalDirectoryNode, InternalNode } from "./vfs/internalTypes";
+import {
+	getNode,
+	getParentDirectory,
+	normalizePath,
+	splitPath,
+} from "./vfs/path";
+import { applySnapshot, createSnapshot } from "./vfs/snapshot";
+import { renderTree } from "./vfs/tree";
+
+/**
+ * In-memory virtual filesystem with tar.gz mirror persistence.
+ *
+ * Paths are normalized to POSIX-like absolute paths. Use
+ * {@link VirtualFileSystem.restoreMirror} on startup and
+ * {@link VirtualFileSystem.flushMirror} to persist pending changes.
+ */
+class VirtualFileSystem {
+	private readonly root: InternalDirectoryNode;
+	private readonly archivePath: string;
+	private dirty = false;
+
+	/**
+	 * Creates a virtual filesystem instance.
+	 *
+	 * @param baseDir Base directory used to resolve mirror archive location.
+	 */
+	constructor(baseDir: string = process.cwd()) {
+		const now = new Date();
+		this.archivePath = path.resolve(baseDir, ".vfs", "mirror.tar.gz");
+		this.root = {
+			type: "directory",
+			name: "",
+			mode: 0o755,
+			createdAt: now,
+			updatedAt: now,
+			children: new Map<string, InternalNode>(),
+		};
+	}
+
+	/**
+	 * Restores filesystem state from mirror archive.
+	 *
+	 * If archive does not exist or cannot be read, creates fresh mirror file.
+	 */
+	public async restoreMirror(): Promise<void> {
+		await fs.mkdir(path.dirname(this.archivePath), { recursive: true });
+
+		try {
+			const compressed = await fs.readFile(this.archivePath);
+			const tarBuffer = gunzipSync(compressed);
+			const snapshot = await readSnapshotFromTar(tarBuffer);
+			applySnapshot(this.root, snapshot);
+			this.dirty = false;
+			return;
+		} catch {
+			await this.flushMirror();
+		}
+	}
+
+	/**
+	 * Persists current filesystem state to mirror archive.
+	 *
+	 * No-op when nothing changed and archive already exists.
+	 */
+	public async flushMirror(): Promise<void> {
+		if (!this.dirty && (await archiveExists(this.archivePath))) {
+			return;
+		}
+
+		await fs.mkdir(path.dirname(this.archivePath), { recursive: true });
+		const snapshotJson = JSON.stringify(createSnapshot(this.root), null, 2);
+		const tarBuffer = await createTarBuffer(snapshotJson);
+		const compressed = gzipSync(tarBuffer);
+		await fs.writeFile(this.archivePath, compressed);
+		this.dirty = false;
+	}
+
+	/**
+	 * Creates directory and any missing parent directories.
+	 *
+	 * @param targetPath Absolute or relative path to directory.
+	 * @param mode POSIX-like mode bits for new directories.
+	 */
+	public mkdir(targetPath: string, mode: number = 0o755): void {
+		const normalized = normalizePath(targetPath);
+		const parts = splitPath(normalized);
+
+		let current = this.root;
+		for (const part of parts) {
+			const existing = current.children.get(part);
+			if (!existing) {
+				const now = new Date();
+				const nextDir: InternalDirectoryNode = {
+					type: "directory",
+					name: part,
+					mode,
+					createdAt: now,
+					updatedAt: now,
+					children: new Map<string, InternalNode>(),
+				};
+				current.children.set(part, nextDir);
+				current.updatedAt = now;
+				this.dirty = true;
+				current = nextDir;
+				continue;
+			}
+
+			if (existing.type !== "directory") {
+				throw new Error(
+					`Cannot create directory '${normalized}': '${part}' is a file.`,
+				);
+			}
+			current = existing;
+		}
+	}
+
+	/**
+	 * Writes UTF-8 text or binary content into file.
+	 *
+	 * Parent directories are created when missing.
+	 *
+	 * @param targetPath Destination file path.
+	 * @param content File content as string or Buffer.
+	 * @param options Optional write behavior (mode, compression).
+	 */
+	public writeFile(
+		targetPath: string,
+		content: string | Buffer,
+		options: WriteFileOptions = {},
+	): void {
+		const normalized = normalizePath(targetPath);
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			true,
+			(pathToCreate) => this.mkdir(pathToCreate),
+		);
+		const now = new Date();
+
+		const rawContent = Buffer.isBuffer(content)
+			? content
+			: Buffer.from(content, "utf8");
+		const shouldCompress = options.compress ?? false;
+		const storedContent = shouldCompress ? gzipSync(rawContent) : rawContent;
+		const existing = parent.children.get(name);
+
+		if (existing && existing.type === "directory") {
+			throw new Error(
+				`Cannot write file '${normalized}': path is a directory.`,
+			);
+		}
+
+		const createdAt = existing?.type === "file" ? existing.createdAt : now;
+		const mode =
+			options.mode ?? (existing?.type === "file" ? existing.mode : 0o644);
+
+		parent.children.set(name, {
+			type: "file",
+			name,
+			mode,
+			createdAt,
+			updatedAt: now,
+			content: storedContent,
+			compressed: shouldCompress,
+		});
+
+		parent.updatedAt = now;
+		this.dirty = true;
+	}
+
+	/**
+	 * Reads file content as UTF-8 text.
+	 *
+	 * Compressed files are transparently decompressed.
+	 *
+	 * @param targetPath Path to file.
+	 * @returns UTF-8 string content.
+	 */
+	public readFile(targetPath: string): string {
+		const node = getNode(this.root, targetPath);
+		if (node.type !== "file") {
+			throw new Error(`Cannot read '${targetPath}': not a file.`);
+		}
+
+		const raw = node.compressed ? gunzipSync(node.content) : node.content;
+		return raw.toString("utf8");
+	}
+
+	/**
+	 * Checks whether node exists at path.
+	 *
+	 * @param targetPath Node path.
+	 * @returns True when file or directory exists.
+	 */
+	public exists(targetPath: string): boolean {
+		try {
+			getNode(this.root, targetPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Updates mode bits for file or directory.
+	 *
+	 * @param targetPath Node path.
+	 * @param mode New POSIX-like mode.
+	 */
+	public chmod(targetPath: string, mode: number): void {
+		const node = getNode(this.root, targetPath);
+		node.mode = mode;
+		node.updatedAt = new Date();
+		this.dirty = true;
+	}
+
+	/**
+	 * Returns metadata for file or directory.
+	 *
+	 * @param targetPath Node path.
+	 * @returns Typed stat object based on node type.
+	 */
+	public stat(targetPath: string): VfsNodeStats {
+		const normalized = normalizePath(targetPath);
+		const node = getNode(this.root, normalized);
+
+		if (node.type === "file") {
+			return {
+				type: "file",
+				name: node.name,
+				path: normalized,
+				mode: node.mode,
+				createdAt: node.createdAt,
+				updatedAt: node.updatedAt,
+				compressed: node.compressed,
+				size: node.content.length,
+			};
+		}
+
+		return {
+			type: "directory",
+			name: node.name,
+			path: normalized,
+			mode: node.mode,
+			createdAt: node.createdAt,
+			updatedAt: node.updatedAt,
+			childrenCount: node.children.size,
+		};
+	}
+
+	/**
+	 * Lists direct children names of directory.
+	 *
+	 * @param dirPath Directory path, defaults to root.
+	 * @returns Sorted child names.
+	 */
+	public list(dirPath: string = "/"): string[] {
+		const node = getNode(this.root, dirPath);
+		if (node.type !== "directory") {
+			throw new Error(`Cannot list '${dirPath}': not a directory.`);
+		}
+
+		return Array.from(node.children.keys()).sort();
+	}
+
+	/**
+	 * Renders ASCII tree view of directory hierarchy.
+	 *
+	 * @param dirPath Directory path, defaults to root.
+	 * @returns Multi-line tree string.
+	 */
+	public tree(dirPath: string = "/"): string {
+		const node = getNode(this.root, dirPath);
+		if (node.type !== "directory") {
+			throw new Error(`Cannot render tree for '${dirPath}': not a directory.`);
+		}
+
+		const rootLabel =
+			dirPath === "/" ? "/" : path.posix.basename(normalizePath(dirPath));
+		return renderTree(node, rootLabel);
+	}
+
+	/**
+	 * Compresses file content with gzip and flags node as compressed.
+	 *
+	 * @param targetPath Path to file.
+	 */
+	public compressFile(targetPath: string): void {
+		const node = getNode(this.root, targetPath);
+		if (node.type !== "file") {
+			throw new Error(`Cannot compress '${targetPath}': not a file.`);
+		}
+
+		if (!node.compressed) {
+			node.content = gzipSync(node.content);
+			node.compressed = true;
+			node.updatedAt = new Date();
+			this.dirty = true;
+		}
+	}
+
+	/**
+	 * Decompresses gzip-compressed file content.
+	 *
+	 * @param targetPath Path to file.
+	 */
+	public decompressFile(targetPath: string): void {
+		const node = getNode(this.root, targetPath);
+		if (node.type !== "file") {
+			throw new Error(`Cannot decompress '${targetPath}': not a file.`);
+		}
+
+		if (node.compressed) {
+			node.content = gunzipSync(node.content);
+			node.compressed = false;
+			node.updatedAt = new Date();
+			this.dirty = true;
+		}
+	}
+
+	/**
+	 * Removes file or directory node.
+	 *
+	 * @param targetPath Path to remove.
+	 * @param options Removal options, including recursive delete.
+	 */
+	public remove(targetPath: string, options: RemoveOptions = {}): void {
+		const normalized = normalizePath(targetPath);
+		if (normalized === "/") {
+			throw new Error("Cannot remove root directory.");
+		}
+
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			false,
+			() => undefined,
+		);
+		const node = parent.children.get(name);
+
+		if (!node) {
+			throw new Error(`Path '${normalized}' does not exist.`);
+		}
+
+		if (
+			node.type === "directory" &&
+			node.children.size > 0 &&
+			!options.recursive
+		) {
+			throw new Error(
+				`Directory '${normalized}' is not empty. Use recursive option.`,
+			);
+		}
+
+		parent.children.delete(name);
+		parent.updatedAt = new Date();
+		this.dirty = true;
+	}
+
+	/**
+	 * Moves or renames node to destination path.
+	 *
+	 * @param fromPath Existing source path.
+	 * @param toPath Destination path.
+	 */
+	public move(fromPath: string, toPath: string): void {
+		const fromNormalized = normalizePath(fromPath);
+		const toNormalized = normalizePath(toPath);
+
+		if (fromNormalized === "/" || toNormalized === "/") {
+			throw new Error("Cannot move root directory.");
+		}
+
+		const { parent: fromParent, name: fromName } = getParentDirectory(
+			this.root,
+			fromNormalized,
+			false,
+			() => undefined,
+		);
+		const node = fromParent.children.get(fromName);
+
+		if (!node) {
+			throw new Error(`Path '${fromNormalized}' does not exist.`);
+		}
+
+		const { parent: toParent, name: toName } = getParentDirectory(
+			this.root,
+			toNormalized,
+			true,
+			(pathToCreate) => this.mkdir(pathToCreate),
+		);
+		if (toParent.children.has(toName)) {
+			throw new Error(`Destination '${toNormalized}' already exists.`);
+		}
+
+		fromParent.children.delete(fromName);
+		node.name = toName;
+		node.updatedAt = new Date();
+		toParent.children.set(toName, node);
+		fromParent.updatedAt = new Date();
+		toParent.updatedAt = new Date();
+		this.dirty = true;
+	}
+}
+
+export default VirtualFileSystem;

package/src/index.ts

@@ -0,0 +1,34 @@
+import { SshClient } from "./SSHMimic/client";
+import { SshMimic } from "./SSHMimic/index";
+import { VirtualUserManager } from "./SSHMimic/users";
+import VirtualFileSystem from "./VirtualFileSystem";
+
+export type {
+	CommandContext,
+	CommandMode,
+	CommandOutcome,
+	CommandResult,
+	NanoEditorSession,
+	ShellModule,
+	SudoChallenge
+} from "./types/commands";
+export type { ExecStream, ShellStream } from "./types/streams";
+export type {
+	RemoveOptions,
+	VfsBaseNode,
+	VfsDirectoryNode,
+	VfsFileNode,
+	VfsNodeStats,
+	VfsNodeType,
+	VfsSnapshot,
+	VfsSnapshotBaseNode,
+	VfsSnapshotDirectoryNode,
+	VfsSnapshotFileNode,
+	VfsSnapshotNode,
+	WriteFileOptions
+} from "./types/vfs";
+
+export {
+	SshClient, VirtualFileSystem, SshMimic as VirtualMachine, VirtualUserManager
+};
+

package/src/standalone.ts

@@ -0,0 +1,14 @@
+import { VirtualMachine } from ".";
+
+const sshHostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
+const sshMimic = new VirtualMachine({ port: 2222, hostname: sshHostname });
+
+sshMimic
+	.start()
+	.then((port: number) => {
+		console.log(`SSH Mimic initialized. Listening on port ${port}.`);
+	})
+	.catch((error: unknown) => {
+		console.error("Failed to start SSH Mimic:", error);
+		process.exit(1);
+	});

package/src/types/commands.ts

@@ -0,0 +1,98 @@
+/** Command invocation mode used by shell runtime. */
+export type CommandMode = "shell" | "exec";
+
+import type {
+	VirtualActiveSession,
+	VirtualUserManager,
+} from "../SSHMimic/users";
+import type VirtualFileSystem from "../VirtualFileSystem";
+
+/**
+ * Normalized command execution output.
+ *
+ * A command can write text, control session lifecycle, request UI state
+ * transitions, and update active identity/cwd.
+ */
+export interface CommandResult {
+	/** Standard output payload to append in terminal. */
+	stdout?: string;
+	/** Standard error payload to append in terminal. */
+	stderr?: string;
+	/** Request full terminal clear before next prompt. */
+	clearScreen?: boolean;
+	/** Request current shell/exec session close. */
+	closeSession?: boolean;
+	/** Optional exit code (default behavior handled by caller). */
+	exitCode?: number;
+	/** Optional cwd to apply for next prompt iteration. */
+	nextCwd?: string;
+	/** Optional user switch for current session state. */
+	switchUser?: string;
+	/** Request opening built-in nano editor workflow. */
+	openEditor?: NanoEditorSession;
+	/** Request opening built-in htop-like screen. */
+	openHtop?: boolean;
+	/** Request sudo password challenge flow. */
+	sudoChallenge?: SudoChallenge;
+}
+
+/** Deferred sudo challenge metadata returned by sudo command. */
+export interface SudoChallenge {
+	/** User currently requesting elevation. */
+	username: string;
+	/** Target identity for elevated command. */
+	targetUser: string;
+	/** Command to execute after successful challenge; null for login shell. */
+	commandLine: string | null;
+	/** True when challenge targets interactive login shell. */
+	loginShell: boolean;
+	/** Prompt text shown before password input. */
+	prompt: string;
+}
+
+/** State payload used by nano command interactive editor flow. */
+export interface NanoEditorSession {
+	/** Final destination path to write when save succeeds. */
+	targetPath: string;
+	/** Temporary scratch path used while editing. */
+	tempPath: string;
+	/** Initial editor content shown to user. */
+	initialContent: string;
+}
+
+/** Runtime context object passed to each command module. */
+export interface CommandContext {
+	/** Authenticated user currently bound to stream. */
+	authUser: string;
+	/** Virtual hostname shown in prompt and banners. */
+	hostname: string;
+	/** User and session manager instance. */
+	users: VirtualUserManager;
+	/** Snapshot of currently active user sessions. */
+	activeSessions: VirtualActiveSession[];
+	/** Original unparsed command line input. */
+	rawInput: string;
+	/** Invocation mode (interactive shell or direct exec). */
+	mode: CommandMode;
+	/** Tokenized arguments excluding command name. */
+	args: string[];
+	/** Current working directory for command execution. */
+	cwd: string;
+	/** Virtual filesystem instance for IO operations. */
+	vfs: VirtualFileSystem;
+}
+
+/** Contract implemented by each shell command module. */
+export interface ShellModule {
+	/** Primary command name used in CLI. */
+	name: string;
+	/** Parameter help snippets displayed by help command. */
+	params: string[];
+	/** Command handler implementation. */
+	run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>;
+	/** Optional alternative command names. */
+	aliases?: string[];
+}
+
+/** Command return union allowing sync or async handlers. */
+export type CommandOutcome = CommandResult | Promise<CommandResult>;

package/src/types/streams.ts

@@ -0,0 +1,32 @@
+/**
+ * Minimal stream contract used by exec command handlers.
+ */
+export interface ExecStream {
+	/** Writes text to stdout channel. */
+	write(data: string): void;
+	/** Signals output completion. */
+	end(): void;
+	/** Sets process-like exit code for exec response. */
+	exit(code: number): void;
+	/** Writable stderr channel. */
+	stderr: {
+		/** Writes text to stderr channel. */
+		write(data: string): void;
+	};
+}
+
+/**
+ * Minimal interactive stream contract used by shell mode.
+ */
+export interface ShellStream {
+	/** Writes text to shell output channel. */
+	write(data: string): void;
+	/** Sets shell exit code on close. */
+	exit(code: number): void;
+	/** Ends shell stream. */
+	end(): void;
+	/** Subscribes to incoming user input chunks. */
+	on(event: "data", listener: (chunk: Buffer) => void): void;
+	/** Subscribes to stream close event. */
+	on(event: "close", listener: () => void): void;
+}

package/src/types/tar-stream.d.ts

@@ -0,0 +1,38 @@
+declare module "tar-stream" {
+	export interface TarStreamEntryHeader {
+		name: string;
+		mode?: number;
+		size?: number;
+		mtime?: Date;
+	}
+
+	export interface TarStreamPack {
+		entry(
+			header: TarStreamEntryHeader,
+			data: string | Buffer,
+			callback?: (error?: Error | null) => void,
+		): void;
+		finalize(): void;
+		destroy?(error?: Error): void;
+		on(event: "data", listener: (chunk: Buffer) => void): this;
+		on(event: "end", listener: () => void): this;
+		on(event: "error", listener: (error: Error) => void): this;
+	}
+
+	export interface TarStreamExtract {
+		on(
+			event: "entry",
+			listener: (
+				header: TarStreamEntryHeader,
+				stream: NodeJS.ReadableStream,
+				next: () => void,
+			) => void,
+		): this;
+		on(event: "finish", listener: () => void): this;
+		on(event: "error", listener: (error: Error) => void): this;
+		end(buffer: Buffer): void;
+	}
+
+	export function pack(): TarStreamPack;
+	export function extract(): TarStreamExtract;
+}