A-Terminal 🖥️

A retro‑style command‑line operating system built with Node.js. Experience the nostalgia of old‑school file managers with modern flair — animations, colored output, and a fully virtual file system.

✨ Features

• Virtual File System – A complete in‑memory tree structure with persistent storage (saves to data/state.json).
• Classic Commands – ls, cd, mkdir, rm, cp, mv, cat, echo, clear, pwd, whoami, date, time, ver, history, exit, and more.
• Input/Output Redirection – Use > (write) and >> (append) to redirect command output to files.
• Tab Completion – Auto‑complete commands and file/directory paths (like a real terminal).
• Command History – Navigate with ↑/↓ arrows; persistent across sessions.
• Batch Scripts (planned) – Run .bat or .sh files.
• Multi‑user (optional) – Can be extended with user login and permissions.
• Beautiful UI – Gradient logos, ASCII art, cowsay welcome, progress bars, and spinners.
• No external dependencies on host – Everything runs inside the virtual sandbox.

🚀 Quick Start

Prerequisites

• Node.js 18 or higher
• npm or yarn

Installation

npm i -g aterminal

Or run locally:

git clone https://github.com/ariq-azmain/aterminal.git
cd aterminal
npm install
npm link

Launch

ater
# or
npx aterminal

You will see a boot animation, then a prompt like:

user@hostname:/home/user$

Start typing commands!

📖 Command Reference

Command Description Examples ls List directory contents ls, ls -la, ls /home cd Change current directory cd .., cd /home/user mkdir Create a directory mkdir myfolder, mkdir -p a/b/c rm Remove files or directories rm file.txt, rm -r folder cp Copy files/directories cp source.txt dest.txt mv Move or rename mv oldname newname cat Display file content cat file.txt echo Print text or redirect echo "Hello" > file.txt clear Clear the screen clear pwd Show current directory pwd whoami Show current username whoami date Show system date date time Show system time time ver Show A-Terminal version ver history Show command history history exit Exit the system exit help List commands or get help help, help ls test Run internal VFS tests test

🧪 Testing the System

After starting, type test to run a comprehensive suite that verifies all VFS operations (mkdir, read/write, rename, remove, path resolution, tab completion). It will report passed/failed tests.

🎨 UI & Animation

· Boot screen – Gradient figlet logo + progress bar. · Loading spinners – ora spinners during VFS init and long commands. · Welcome message – Cowsay + boxen. · Colored output – Different colors for directories, errors, prompts. · Tab completion hints – Real‑time suggestions.

📂 Project Structure

aterminal/
├── index.js                 # Entry point (readline, boot, event loop)
├── config/
│   └── default.json         # Default configuration
├── src/
│   ├── cli/
│   │   ├── command-parser.js
│   │   └── executor.js
│   ├── commands/
│   │   ├── index.js
│   │   └── builtin/         # All command implementations
│   ├── vfs/
│   │   ├── file-system.js
│   │   ├── directory.js
│   │   └── file.js
│   ├── user/
│   │   └── session.js       # Stores cwd, history (no login by default)
│   ├── process/
│   │   └── job-control.js   # Background jobs (placeholder)
│   ├── persistence/
│   │   └── storage.js       # Save/load state.json
│   └── utils/
│       ├── helpers.js
│       └── ui.js            # Animations, boxen, cowsay
├── data/
│   └── state.json           # Persistent VFS state (created automatically)
└── README.md

🔧 Configuration

Edit config/default.json to change:

· dataPath – where state.json is stored. · promptFormat – custom prompt style (default: {user}@{host}:{cwd}$). · colors – color mapping for prompt, errors, info. · autoSaveIntervalMs – how often to auto‑save state.

🛠️ Development

Adding a new command

1. Create a file src/commands/builtin/mycmd.js.
2. Export an object with an execute(context) method.
3. Optionally add a help property.
4. Reboot the system – the command registry auto‑loads it.

Example:

export default {
    async execute(context) {
        const { args, stdout } = context;
        stdout.write("Hello from mycmd!\n");
        return "";
    },
    help: "mycmd – demonstrates custom command"
};

Running in dev mode

npm run dev   # uses nodemon to auto‑restart on changes

Debugging Tab Completion

If Tab causes the program to exit, check that no process.stdin.on('keypress') listeners are active. Use the built‑in rl.completer only.

🐛 Known Issues & Limitations

· Tab completion – In some environments, using completer inside createInterface works; we fixed early crashes. If it still exits, please open an issue. · Recursive copy – cp -r not yet implemented (but mkdir -p works). · Background jobs – Placeholder only; not functional yet. · Piping – Basic pipeline works for two commands (e.g., cat file | grep text). More than two may fail.

🤝 Contributing

Contributions are welcome! Please follow the existing code style and add tests for new commands.

📄 License

MIT © Your Name

🙏 Acknowledgements

· chalk – terminal styling · ora – spinners · figlet – ASCII art · cowsay – cowsay messages · boxen – bordered boxes · fs-extra – persistent JSON storage

Enjoy your retro terminal experience! 🎉