Porsh (Interactive Shell & Virtual File System/OS)

An interactive Unix-like Shell and Virtual File System (VFS) engine implemented in TypeScript.

Porsh is a high-reliability Unix-like interactive shell and Virtual File System (VFS) engine implemented in TypeScript. It brings core operating system primitives into user-space, featuring an in-memory nested inode tree, two-way state synchronization with physical storage, strict directory sandboxing (chroot jail model), and transactional atomic I/O operations, all exposed through an interactive command-line interface.

---

📝 Features

• PT-BR Interface: Full command suite built specifically for Brazilian Portuguese speakers (listar, carq, apagar, renomear).
• 🗂️ Virtual File System (VFS): An in-memory object-oriented nested tree (IVfsNode) that syncs automatically with the physical disk.
• 🔁 2-Way Sync (Smart Boot): Recovers physically deleted files based on memory state, and pulls physical files into the VFS on boot.
• 🛡️ Kernel Sandboxing: Anti-Directory-Traversal protection. It creates a chroot jail model that prevents users from escaping their /home environment.
• ⚛️ Atomic I/O Operations: Implements atomic writing (temp-to-rename) to prevent tree corruption during sudden process terminations.
• 🛑 POSIX-Compliant Signaling: Graceful exit handling for SIGINT (Ctrl+C) and EOF (Ctrl+D), mimicking authentic Linux bash behavior.
• ⚡ Zero-Overhead Runtime: Built to run natively on Node.js (using Type Stripping) or fast runtimes like Bun and Deno.

---

🏗️ Architecture

The codebase applies solid design patterns (Command Pattern, Singletons) and strictly separates Kernel space from User space:

graph TD;
    CLI[User Space: CLI & REPL] --> Auth[Auth Module];
    CLI --> Commands[Command Parsers];
    Commands --> VFS[VFS Engine Singleton];
    VFS --> Security[Path Sandboxing];
    Security --> IO[Atomic File I/O];
    IO --> OS[(Physical OS Disk)];

Loading

• 📂 src/cli/ — User space (REPL loop, UI, and Command Pattern implementation).
• 📂 src/config/ — Static database (Source of Truth) and user credentials.
• 📂 src/core/ — Kernel space (Sandboxing, VFS state, and atomic I/O).

---

💻 Commands

Porsh supports a complete ecosystem for file management.

Directory Navigation

Command	Parameters	Description
cdir	<name>	Creates a new directory.
rdir	<name>	Removes a directory (only if empty).
mudar	<path>	Changes the current working directory.
atual	-	Prints the absolute path of the current directory.
listar	-	Lists files and subfolders in alphabetical order.
listarinv	-	Lists files and subfolders in reverse alphabetical order.
listartudo	-	Recursively lists the entire directory tree.

File Operations

Command	Parameters	Description
carq	<name>	Creates an empty file (touch).
ler	<name>	Reads and displays file content via streaming (cat).
apagar	<target>	Recursively deletes a file or directory (rm -rf).
copiar	<src> <dst>	Copies a file/folder, assigning new virtual IDs.
mover	<src> <dst>	Moves a file/folder.
renomear	<old> <new>	Renames a file/folder in the same directory.
buscar	<name>	Deep search (DFS) for a file.
listaratr	<target>	Shows disk attributes and creation date.

System Utilities

Command	Parameters	Description
alterarusr	<login>	Switches user sessions.
deletarusr	<login>	Deletes a user environment and revokes access.
resetar	-	Formats the VFS, wiping the disk and rebuilding the system.
clear	-	Clears the terminal screen.
quit	-	Exits the shell cleanly.

---

🚀 Getting Started

1. Prerequisites

• Node.js (v24+) or Bun (v1.x)
• Git

2. Running the Project

git clone https://github.com/LDrawe/porsh.git
cd porsh

npm install
npm start

---

🧪 Testing & Code Coverage

The architecture features an extensive test suite built with the Node.js Native Test Runner (node:test and node:assert), continuously validating kernel invariants, atomic I/O, path sanitization, and Path Traversal exploits.

npm test              # Run the 67 automated native integration and unit tests
npm run test:coverage # Generate the native V8 coverage report

📊 Coverage Report

Metric	Coverage	Details
Lines	98.78%	Production-grade execution path verification
Branches	94.19%	Resilient conditional and error-handling coverage
Functions	85.71%	Core functions verified across all modules
Test Suites	14 / 14 Passed	67 tests passing (0 failures)