bscript-cli 1.0.0

package/Docs/README.md

@@ -0,0 +1,157 @@
+<img src="./Images/BScript-baner.png" width="300" alt="BScript"/>
+
+# BScript-CLI <img src="./Images/Logo.png" width="24" alt=""/>
+
+**Interactive Command-Line Script Interpreter with Dynamic Command Loading**
+
+BScript is a powerful Node.js-based command-line interface framework that allows you to create interactive terminal applications with dynamically loaded commands, permission-based access control, and built-in command history management.
+
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org/)
+[![npm](https://img.shields.io/npm/v/@beiser/bscript-cli.svg)](https://www.npmjs.com/package/bscript)
+[![License](https://img.shields.io/github/license/BEISER901/bscript-cli.svg)](./LICENSE)
+
+---
+
+## ✨ Key Features
+
+- ✅ **Dynamic Command Loading** — Load commands from multiple directories with hot-reload support
+- ✅ **Permission System** — Fine-grained role-based access control for commands
+- ✅ **Interactive Terminal UI** — Full terminal control with cursor positioning and formatting
+- ✅ **Command History** — Persistent command history with navigation
+- ✅ **Script Execution** — Execute inline scripts or load from files with `-e` and `script` commands
+- ✅ **Event-Driven Architecture** — Built on Node.js EventEmitter for extensibility
+- ✅ **Custom Sandboxing** — Safe command execution with isolated contexts
+- ✅ **Command Aliases** — Support multiple names for a single command
+- ✅ **Loader Animation** — Async operation feedback with visual animations
+
+---
+
+## 📌 Useful Links
+
+| Link | Description |
+|------|-------------|
+| **[Syntax Reference](https://github.com/BEISER901/bscript-runner/blob/main/Docs/BScript/SYNTAX.md)** | A complete reference for the BScript language syntax. |
+| **[CLI Reference](./BScript/REFERENCE-CLI.md)** | Available BScript commands and their declaration. |
+| **[bscript-runner](https://github.com/BEISER901/bscript-runner)** | The bscript-runner trans-compiler. |
+| **[Getting Started](./TUTORIAL.md)** | Installation and first steps |
+| **[API Reference](./REFERENCE.md)** | Complete public API documentation |
+| **[Technical](./TECHNICAL.md)** | Internal architecture and implementation |
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+#### Global Installation
+
+**Using npm**
+```bash
+npm install -g @beiser/bscript-cli
+```
+
+**Using pnpm**
+```bash
+pnpm add -g @beiser/bscript-cli
+```
+
+**Using yarn**
+```bash
+yarn global add @beiser/bscript-cli
+```
+
+---
+
+### Basic Usage
+
+```javascript
+const BScript = require("@beiser/bscript-cli");
+
+// Create a new BScript instance
+const cmd = new BScript();
+
+// Set default permissions
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.default];
+
+// Load commands from default locations
+cmd.updateCommands();
+
+// Start interactive mode
+cmd.Start();
+```
+
+---
+
+### Command-Line Interface
+
+```bash
+# Start interactive mode
+bscript
+
+# Execute inline script
+bscript -e "your script code"
+
+# Load and execute a script file
+bscript script path/to/file.js
+
+# Show help
+bscript --help
+
+# Show version
+bscript --version
+```
+
+---
+
+### Getting Started
+
+1. Install the package via npm
+2. Create a BScript instance with desired configuration
+3. Define commands in `.js` files within your commands directory
+4. Update commands to load them into the system
+5. Start the interactive interface or execute scripts
+
+For a complete guide see **[TUTORIAL.md](./TUTORIAL.md)**.
+
+---
+
+## 📚 Documentation
+
+- **[Getting Started](./TUTORIAL.md)** — Installation and usage guide
+- **[API Reference](./REFERENCE.md)** — Full public API documentation
+- **[Technical](./TECHNICAL.md)** — Architecture and internal implementation
+
+---
+
+## 🛠 Core Modules
+
+- **BScript** — Main class for managing commands, permissions, and terminal interaction
+- **TerminalCommandController** — Handles terminal I/O and user input processing
+- **BScriptHistory** — Manages persistent command history across sessions
+- **CMDPermissions** — Permission constants for access control
+- **BScriptRunner** — Script execution engine (external dependency)
+
+---
+
+## 📦 Requirements
+
+- Node.js **18+**
+- npm / pnpm / yarn
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome. Please read **[TECHNICAL.md](./TECHNICAL.md)** before submitting a Pull Request.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**.
+
+See the **[LICENSE](./LICENSE)** file for details.
+
+---
+
+**Made with ❤️ for the Node.js ecosystem**