typescript-virtual-container 1.1.0 → 1.1.1-c

package/dist/modules/shellRuntime.js

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function toTtyLines(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .replace(/\n/g, "\r\n");
+}
+export function withTerminalSize(command, terminalSize) {
+    const cols = Number.isFinite(terminalSize.cols) && terminalSize.cols > 0
+        ? Math.floor(terminalSize.cols)
+        : 80;
+    const rows = Number.isFinite(terminalSize.rows) && terminalSize.rows > 0
+        ? Math.floor(terminalSize.rows)
+        : 24;
+    return `stty cols ${cols} rows ${rows} 2>/dev/null; ${command}`;
+}
+export function resolvePath(base, inputPath) {
+    if (!inputPath || inputPath.trim() === "" || inputPath === ".") {
+        return base;
+    }
+    return inputPath.startsWith("/")
+        ? path.posix.normalize(inputPath)
+        : path.posix.normalize(path.posix.join(base, inputPath));
+}
+export async function collectChildPids(parentPid) {
+    try {
+        const childrenRaw = await readFile(`/proc/${parentPid}/task/${parentPid}/children`, "utf8");
+        const directChildren = childrenRaw
+            .trim()
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((value) => Number.parseInt(value, 10))
+            .filter((pid) => Number.isInteger(pid) && pid > 0);
+        const nested = await Promise.all(directChildren.map((pid) => collectChildPids(pid)));
+        return [...directChildren, ...nested.flat()];
+    }
+    catch {
+        return [];
+    }
+}
+export async function getVisibleHtopPidList(rootPid = process.pid) {
+    const descendants = await collectChildPids(rootPid);
+    const unique = Array.from(new Set(descendants)).sort((a, b) => a - b);
+    if (unique.length === 0) {
+        return null;
+    }
+    return unique.join(",");
+}

package/dist/standalone.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=standalone.d.ts.map

package/dist/standalone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.d.ts","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":""}

package/dist/standalone.js

@@ -0,0 +1,25 @@
+import { VirtualShell, VirtualSshServer } from ".";
+const hostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
+const virtualShell = new VirtualShell(hostname);
+virtualShell.addCommand("demo", [], () => {
+    return {
+        stdout: "This is a demo command. It does nothing useful.",
+        exitCode: 0,
+    };
+});
+new VirtualSshServer({
+    port: 2222,
+    hostname,
+    shell: virtualShell,
+})
+    .start()
+    .then((port) => {
+    // if (!sshMimic) console.error("Failed to initialize SSH Mimic shell.");
+    // else {
+    console.log(`SSH Mimic initialized. Listening on port ${port}.`);
+    // }
+})
+    .catch((error) => {
+    console.error("Failed to start SSH Mimic:", error);
+    process.exit(1);
+});

package/dist/types/commands.d.ts

@@ -0,0 +1,89 @@
+/** Command invocation mode used by shell runtime. */
+export type CommandMode = "shell" | "exec";
+import type { VirtualShell } from "../VirtualShell";
+import type { VirtualActiveSession } from "../VirtualUserManager";
+/**
+ * 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;
+    /** 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[];
+    /** Virtual shell instance. */
+    shell: VirtualShell;
+    /** Optional stdin payload (used by pipes/redirections). */
+    stdin?: string;
+    /** Current working directory for command execution. */
+    cwd: string;
+}
+/** 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>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/types/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/types/commands.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC7B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2DAA2D;IAC3D,UAAU,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IACjC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC9B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,cAAc,EAAE,oBAAoB,EAAE,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,8BAA8B;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrE,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC"}

package/dist/types/pipeline.d.ts

@@ -0,0 +1,23 @@
+/** Represents a single command in a pipeline. */
+export interface PipelineCommand {
+    /** Command name */
+    name: string;
+    /** Command arguments */
+    args: string[];
+    /** Input redirection file path (< file) */
+    inputFile?: string;
+    /** Output redirection file path (> file) */
+    outputFile?: string;
+    /** Append to output file (>> file) */
+    appendOutput?: boolean;
+}
+/** Represents a parsed shell pipeline */
+export interface Pipeline {
+    /** List of commands in the pipeline */
+    commands: PipelineCommand[];
+    /** Whether this is a valid pipeline */
+    isValid: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/types/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/types/pipeline.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC/B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACxB,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/types/streams.d.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;
+}
+//# sourceMappingURL=streams.d.ts.map

package/dist/types/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../src/types/streams.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,qCAAqC;IACrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iCAAiC;IACjC,GAAG,IAAI,IAAI,CAAC;IACZ,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+BAA+B;IAC/B,MAAM,EAAE;QACP,qCAAqC;QACrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,2CAA2C;IAC3C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qCAAqC;IACrC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yBAAyB;IACzB,GAAG,IAAI,IAAI,CAAC;IACZ,gDAAgD;IAChD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,wCAAwC;IACxC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/C"}

package/dist/types/vfs.d.ts

@@ -0,0 +1,71 @@
+/** Supported virtual node kinds. */
+export type VfsNodeType = "file" | "directory";
+/** Shared metadata fields available on file and directory stats. */
+export interface VfsBaseNode {
+    /** Node name without parent path. */
+    name: string;
+    /** Absolute normalized node path. */
+    path: string;
+    /** POSIX-like mode bits. */
+    mode: number;
+    /** Node creation timestamp. */
+    createdAt: Date;
+    /** Last update timestamp. */
+    updatedAt: Date;
+}
+/** Stat shape returned for file nodes. */
+export interface VfsFileNode extends VfsBaseNode {
+    type: "file";
+    /** True when file content stored as gzip bytes. */
+    compressed: boolean;
+    /** Stored byte length (compressed when compressed=true). */
+    size: number;
+}
+/** Stat shape returned for directory nodes. */
+export interface VfsDirectoryNode extends VfsBaseNode {
+    type: "directory";
+    /** Number of direct children in directory. */
+    childrenCount: number;
+}
+/** Union of file and directory stat responses. */
+export type VfsNodeStats = VfsFileNode | VfsDirectoryNode;
+/** Optional behavior flags for writeFile operations. */
+export interface WriteFileOptions {
+    /** POSIX-like mode to apply on create or overwrite. */
+    mode?: number;
+    /** Store content compressed with gzip. */
+    compress?: boolean;
+}
+/** Optional behavior flags for remove operations. */
+export interface RemoveOptions {
+    /** Allow deleting non-empty directory trees. */
+    recursive?: boolean;
+}
+/** Base snapshot node schema used for archive serialization. */
+export interface VfsSnapshotBaseNode {
+    name: string;
+    mode: number;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 update timestamp. */
+    updatedAt: string;
+}
+/** Serialized snapshot shape for file nodes. */
+export interface VfsSnapshotFileNode extends VfsSnapshotBaseNode {
+    type: "file";
+    compressed: boolean;
+    /** Base64-encoded raw file bytes. */
+    contentBase64: string;
+}
+/** Serialized snapshot shape for directory nodes. */
+export interface VfsSnapshotDirectoryNode extends VfsSnapshotBaseNode {
+    type: "directory";
+    children: VfsSnapshotNode[];
+}
+/** Union of serialized snapshot node variants. */
+export type VfsSnapshotNode = VfsSnapshotFileNode | VfsSnapshotDirectoryNode;
+/** Top-level serialized filesystem snapshot. */
+export interface VfsSnapshot {
+    root: VfsSnapshotDirectoryNode;
+}
+//# sourceMappingURL=vfs.d.ts.map

package/dist/types/vfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../../src/types/vfs.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/C,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC3B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,IAAI,CAAC;IAChB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACb;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE1D,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAChC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC7B,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACpE,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,kDAAkD;AAClD,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,wBAAwB,CAAC;AAE7E,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,wBAAwB,CAAC;CAC/B"}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "typescript-virtual-container",
   "description": "In-memory SSH server with virtual filesystem and typed programmatic API",
-  "module": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.1.1c",
   "license": "MIT",
   "keywords": [
     "ssh",
@@ -20,6 +21,7 @@
     "lint": "bunx --bun @biomejs/biome lint ./src",
     "lint:write": "bunx --bun @biomejs/biome lint --write ./src",
     "test": "bunx --bun @biomejs/biome test ./src",
+    "build": "tsc --project tsconfig.json",
     "deploy:npm": "npm publish --access public"
   },
   "devDependencies": {

package/src/{SSHMimic/client.ts → SSHClient/index.ts}

@@ -1,6 +1,6 @@
+import { runCommand } from "../commands";
 import type { CommandResult } from "../types/commands";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand } from "../VirtualShell/commands";
 
 /**
  * Programmatic client for executing shell commands against a virtual shell.
@@ -154,7 +154,7 @@ export class SshClient {
 		}
 
 		try {
-			vfs.writeFile(path, content);
+			this.shell.writeFileAsUser(this.username, path, content);
 			return { stdout: `File '${path}' written`, exitCode: 0 };
 		} catch (error) {
 			return {

package/src/SSHMimic/exec.ts

@@ -1,6 +1,6 @@
+import { runCommand } from "../commands";
 import type { ExecStream } from "../types/streams";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand } from "../VirtualShell/commands";
 
 function toTtyLines(text: string): string {
 	return text

package/src/SSHMimic/executor.ts

@@ -1,8 +1,8 @@
+import { runCommand as runSingleCommand } from "../commands";
+import { resolvePath } from "../commands/helpers";
 import type { CommandMode, CommandResult } from "../types/commands";
 import type { Pipeline, PipelineCommand } from "../types/pipeline";
 import type { VirtualShell } from "../VirtualShell";
-import { runCommand as runSingleCommand } from "../VirtualShell/commands";
-import { resolvePath } from "../VirtualShell/commands/helpers";
 
 /**
  * Execute a parsed pipeline, chaining commands and handling redirections.
@@ -90,12 +90,12 @@ async function executeSingleCommandWithRedirections(
 			if (cmd.appendOutput) {
 				try {
 					const existing = shell.vfs.readFile(outputPath);
-					shell.vfs.writeFile(outputPath, existing + output);
+					shell.writeFileAsUser(authUser, outputPath, existing + output);
 				} catch {
-					shell.vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, outputPath, output);
 				}
 			} else {
-				shell.vfs.writeFile(outputPath, output);
+				shell.writeFileAsUser(authUser, outputPath, output);
 			}
 			return { ...result, stdout: "" };
 		} catch {
@@ -165,12 +165,12 @@ async function executePipelineChain(
 				if (cmd.appendOutput) {
 					try {
 						const existing = shell.vfs.readFile(outputPath);
-						shell.vfs.writeFile(outputPath, existing + output);
+						shell.writeFileAsUser(authUser, outputPath, existing + output);
 					} catch {
-						shell.vfs.writeFile(outputPath, output);
+						shell.writeFileAsUser(authUser, outputPath, output);
 					}
 				} else {
-					shell.vfs.writeFile(outputPath, output);
+					shell.writeFileAsUser(authUser, outputPath, output);
 				}
 				currentOutput = "";
 			} catch {

package/src/VirtualFileSystem/index.ts

@@ -24,6 +24,18 @@ class VirtualFileSystem {
 	private readonly archivePath: string;
 	private dirty = false;
 
+	private computeNodeUsageBytes(node: InternalNode): number {
+		if (node.type === "file") {
+			return node.content.length;
+		}
+
+		let total = 0;
+		for (const child of node.children.values()) {
+			total += this.computeNodeUsageBytes(child);
+		}
+		return total;
+	}
+
 	/**
 	 * Creates a virtual filesystem instance.
 	 *
@@ -287,6 +299,20 @@ class VirtualFileSystem {
 		return renderTree(node, rootLabel);
 	}
 
+	/**
+	 * Computes total stored file bytes under a path.
+	 *
+	 * File usage is based on in-memory stored bytes, including compressed
+	 * payload size when files are marked as compressed.
+	 *
+	 * @param targetPath File or directory path to measure, defaults to root.
+	 * @returns Total byte usage for file content under target path.
+	 */
+	public getUsageBytes(targetPath: string = "/"): number {
+		const node = getNode(this.root, targetPath);
+		return this.computeNodeUsageBytes(node);
+	}
+
 	/**
 	 * Compresses file content with gzip and flags node as compressed.
 	 *

package/src/VirtualShell/index.ts

@@ -1,9 +1,9 @@
 import { randomBytes } from "node:crypto";
+import { createCustomCommand, registerCommand, runCommand } from "../commands";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
 import VirtualFileSystem from "../VirtualFileSystem";
 import { VirtualUserManager } from "../VirtualUserManager";
-import { createCustomCommand, registerCommand, runCommand } from "./commands";
 import { startShell } from "./shell";
 
 export interface ShellProperties {
@@ -170,6 +170,22 @@ class VirtualShell {
 	public getHostname(): string {
 		return this?.hostname;
 	}
+
+	/**
+	 * Writes a file on behalf of a user with quota enforcement.
+	 *
+	 * @param authUser User performing the write.
+	 * @param targetPath Destination path.
+	 * @param content File content.
+	 */
+	public writeFileAsUser(
+		authUser: string,
+		targetPath: string,
+		content: string | Buffer,
+	): void {
+		this.users.assertWriteWithinQuota(authUser, targetPath, content);
+		this.vfs.writeFile(targetPath, content);
+	}
 }
 
 export { VirtualShell };

package/src/VirtualShell/shell.ts

@@ -1,12 +1,22 @@
-import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import type { ShellProperties, VirtualShell } from ".";
+import { getCommandNames, runCommand } from "../commands";
+import {
+	spawnHtopProcess,
+	spawnNanoEditorProcess,
+} from "../modules/shellInteractive";
+import {
+	getVisibleHtopPidList,
+	resolvePath,
+	type TerminalSize,
+	toTtyLines,
+} from "../modules/shellRuntime";
 import { formatLoginDate } from "../SSHMimic/loginFormat";
 import { buildPrompt } from "../SSHMimic/prompt";
 import type { ShellStream } from "../types/streams";
 import type VirtualFileSystem from "../VirtualFileSystem";
-import { getCommandNames, runCommand } from "./commands";
 
 interface NanoSession {
 	kind: "nano" | "htop";
@@ -24,22 +34,6 @@ interface PendingSudo {
 	buffer: string;
 }
 
-function shellQuote(value: string): string {
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
-interface TerminalSize {
-	cols: number;
-	rows: number;
-}
-
-function toTtyLines(text: string): string {
-	return text
-		.replace(/\r\n/g, "\n")
-		.replace(/\r/g, "\n")
-		.replace(/\n/g, "\r\n");
-}
-
 export function startShell(
 	properties: ShellProperties,
 	stream: ShellStream,
@@ -68,60 +62,6 @@ export function startShell(
 		`[${sessionId}] Shell started for user '${authUser}' at ${remoteAddress}`,
 	);
 
-	async function collectChildPids(parentPid: number): Promise<number[]> {
-		try {
-			const childrenRaw = await readFile(
-				`/proc/${parentPid}/task/${parentPid}/children`,
-				"utf8",
-			);
-			const directChildren = childrenRaw
-				.trim()
-				.split(/\s+/)
-				.filter(Boolean)
-				.map((value) => Number.parseInt(value, 10))
-				.filter((pid) => Number.isInteger(pid) && pid > 0);
-
-			const nested = await Promise.all(
-				directChildren.map((pid) => collectChildPids(pid)),
-			);
-			return [...directChildren, ...nested.flat()];
-		} catch {
-			return [];
-		}
-	}
-
-	async function getVisibleHtopPidList(): Promise<string | null> {
-		const rootPid = process.pid;
-		const descendants = await collectChildPids(rootPid);
-		const unique = Array.from(new Set(descendants)).sort((a, b) => a - b);
-		if (unique.length === 0) {
-			return null;
-		}
-
-		return unique.join(",");
-	}
-
-	function withTerminalSize(command: string): string {
-		const cols =
-			Number.isFinite(terminalSize.cols) && terminalSize.cols > 0
-				? Math.floor(terminalSize.cols)
-				: 80;
-		const rows =
-			Number.isFinite(terminalSize.rows) && terminalSize.rows > 0
-				? Math.floor(terminalSize.rows)
-				: 24;
-		return `stty cols ${cols} rows ${rows} 2>/dev/null; ${command}`;
-	}
-
-	function resolvePath(base: string, inputPath: string): string {
-		if (!inputPath || inputPath.trim() === "" || inputPath === ".") {
-			return base;
-		}
-		return inputPath.startsWith("/")
-			? path.posix.normalize(inputPath)
-			: path.posix.normalize(path.posix.join(base, inputPath));
-	}
-
 	function renderLine(): void {
 		const prompt = buildCurrentPrompt();
 		stream.write(`\r${prompt}${lineBuffer}\u001b[K`);
@@ -236,7 +176,11 @@ export function startShell(
 		if (activeSession.kind === "nano") {
 			try {
 				const updatedContent = await readFile(activeSession.tempPath, "utf8");
-				shell.vfs.writeFile(activeSession.targetPath, updatedContent);
+				shell.writeFileAsUser(
+					authUser,
+					activeSession.targetPath,
+					updatedContent,
+				);
 				await shell.vfs.flushMirror();
 			} catch {
 				// If temp file does not exist, nano exited without writing.
@@ -261,23 +205,7 @@ export function startShell(
 			await writeFile(tempPath, initialContent, "utf8");
 		}
 
-		const command = withTerminalSize(`nano -- ${shellQuote(tempPath)}`);
-		const editor = spawn("script", ["-qfec", command, "/dev/null"], {
-			stdio: ["pipe", "pipe", "pipe"],
-			env: {
-				...process.env,
-				// biome-ignore lint/style/useNamingConvention: TERM is an environment variable conventionally in uppercase
-				TERM: process.env.TERM ?? "xterm-256color",
-			},
-		});
-
-		editor.stdout.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
-
-		editor.stderr.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
+		const editor = spawnNanoEditorProcess(tempPath, terminalSize, stream);
 
 		editor.on("error", (error: Error) => {
 			stream.write(`nano: ${error.message}\r\n`);
@@ -303,23 +231,7 @@ export function startShell(
 			return;
 		}
 
-		const command = withTerminalSize(`htop -p ${shellQuote(pidList)}`);
-		const monitor = spawn("script", ["-qfec", command, "/dev/null"], {
-			stdio: ["pipe", "pipe", "pipe"],
-			env: {
-				...process.env,
-				// biome-ignore lint/style/useNamingConvention: TERM is an environment variable conventionally in uppercase
-				TERM: process.env.TERM ?? "xterm-256color",
-			},
-		});
-
-		monitor.stdout.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
-
-		monitor.stderr.on("data", (data: Buffer) => {
-			stream.write(data.toString("utf8"));
-		});
+		const monitor = spawnHtopProcess(pidList, terminalSize, stream);
 
 		monitor.on("error", (error: Error) => {
 			stream.write(`htop: ${error.message}\r\n`);