bscript-cli 1.0.0

package/Docs/TUTORIAL.md

@@ -0,0 +1,604 @@
+# Getting Started
+
+Practical step-by-step guide for installing, configuring, and using BScript to build interactive command-line applications.
+
+This guide focuses on real-world usage with complete examples. Detailed API information is available in **REFERENCE.md**.
+
+---
+
+## Contents
+
+- [1. Installation](#1-installation)
+- [2. Importing the package](#2-importing-the-package)
+- [3. Initial setup](#3-initial-setup)
+- [4. Core usage scenarios](#4-core-usage-scenarios)
+- [5. Useful examples](#5-useful-examples)
+- [6. Best practices](#6-best-practices)
+- [See also](#see-also)
+
+---
+
+<a id="1-installation"></a>
+
+## 1. Installation
+
+### npm
+
+```bash
+npm install bscript
+```
+
+### pnpm
+
+```bash
+pnpm add bscript
+```
+
+### yarn
+
+```bash
+yarn add bscript
+```
+
+---
+
+<a id="2-importing-the-package"></a>
+
+## 2. Importing the package
+
+### CommonJS
+
+```javascript
+const BScript = require("bscript");
+```
+
+### ES Modules
+
+```javascript
+import BScript from "bscript";
+```
+
+or
+
+```javascript
+import { BScript } from "bscript";
+```
+
+---
+
+<a id="3-initial-setup"></a>
+
+## 3. Initial setup
+
+### Basic Initialization
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript({
+    commandsPaths: ["./commands"],
+    cmdRootPermissions: [0]  // default permission level
+});
+
+cmd.updateCommands();
+```
+
+### Description
+
+When you create a new BScript instance, you're initializing an interactive command-line environment. The constructor accepts:
+
+- **commandsPaths**: Array of directories to scan for command files
+- **cmdRootPermissions**: Permission levels that determine which commands are available
+- **cmdPermissionsHistory**: Initial permission stack for nested contexts
+
+After configuration, call `updateCommands()` to load all command files from specified directories. BScript scans recursively and filters commands based on your permission settings.
+
+---
+
+<a id="4-core-usage-scenarios"></a>
+
+## 4. Core usage scenarios
+
+### 4.1 Starting Interactive Mode
+
+Start a fully-featured interactive command-line interface.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript();
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.default];
+cmd.updateCommands();
+
+// Begin interactive mode with prompt
+cmd.Start();
+```
+
+### Output
+
+```
+<help>? echo "Welcome to BScript"
+> Welcome to BScript
+<help>? help
+```
+
+---
+
+### 4.2 Executing Scripts from Code
+
+Execute BScript code programmatically without interactive mode.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+    cmd.perrmissionsKeys.default,
+    cmd.perrmissionsKeys.script
+];
+cmd.updateCommands();
+
+// Execute inline script
+const scriptFn = cmd.bscript('echo "Hello from script"');
+scriptFn();
+```
+
+---
+
+### 4.3 Working with Permissions
+
+Create different access levels for different users or contexts.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript({
+    perrmissionsKeys: {
+        default: 0,
+        admin: 100,
+        script: 999
+    }
+});
+
+// User mode - only default commands available
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.default];
+cmd.updateCommands();
+cmd.Start();
+
+// Later: switch to admin mode
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.admin];
+cmd.updateCommands();
+```
+
+---
+
+### 4.4 Loading Commands from Multiple Directories
+
+Organize commands in separate folders and load them all.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript({
+    commandsPaths: [
+        "./built-in-commands",
+        "./user-commands",
+        "./admin-commands"
+    ]
+});
+
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.default];
+cmd.updateCommands();
+cmd.Start();
+```
+
+---
+
+### 4.5 Adding Commands Programmatically
+
+Register commands without creating files.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript();
+
+// Add a simple echo command
+cmd.createCommand({
+    name: "echo",
+    description: "Echo text to console",
+    syntax: "echo [text...]",
+    execute: (args) => {
+        console.log(args.join(" "));
+    }
+});
+
+// Add a math command
+cmd.createCommand({
+    name: "add",
+    description: "Add numbers",
+    syntax: "add [number1] [number2] ...",
+    execute: (args) => {
+        const sum = args.reduce((a, b) => a + parseFloat(b), 0);
+        console.log("Result:", sum);
+    }
+});
+
+cmd.Start();
+```
+
+### Expected output
+
+```
+<help>? add 5 10 15
+Result: 30
+<help>? echo Hello World
+Hello World
+```
+
+---
+
+### 4.6 Using the Loader Animation
+
+Display loading animation while executing async operations.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript();
+
+cmd.createCommand({
+    name: "fetch-data",
+    description: "Fetch data with loading animation",
+    execute: () => {
+        cmd.loader(async (done, waitForPromise, startAnimation) => {
+            // Perform async work
+            const result = await waitForPromise(async () => {
+                return new Promise(resolve => {
+                    setTimeout(() => {
+                        resolve("Data loaded successfully!");
+                    }, 3000);
+                });
+            });
+            
+            console.log(result);
+            done();
+        });
+    }
+});
+
+cmd.Start();
+```
+
+### Output
+
+```
+<help>? fetch-data
+Loading...
+Data loaded successfully!
+```
+
+---
+
+<a id="5-useful-examples"></a>
+
+## 5. Useful Examples
+
+### Example 1 — Complete CLI Application
+
+Build a complete calculator CLI with multiple commands and permissions.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript({
+    perrmissionsKeys: {
+        default: 0,
+        admin: 100
+    }
+});
+
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.default];
+
+// Basic math commands
+cmd.createCommand({
+    name: "add",
+    description: "Add numbers: add 2 3 4",
+    execute: (args) => {
+        const result = args.reduce((a, b) => a + parseFloat(b), 0);
+        console.log(`Result: ${result}`);
+    }
+});
+
+cmd.createCommand({
+    name: "multiply",
+    description: "Multiply numbers: multiply 2 3 4",
+    execute: (args) => {
+        const result = args.reduce((a, b) => a * parseFloat(b), 1);
+        console.log(`Result: ${result}`);
+    }
+});
+
+// Admin-only command
+cmd.createCommand({
+    name: "admin-reset",
+    description: "Reset calculator",
+    perms: [cmd.perrmissionsKeys.admin],
+    execute: () => {
+        console.log("Calculator reset");
+    }
+});
+
+cmd.updateCommands();
+cmd.Start();
+```
+
+### Expected output
+
+```
+<help>? add 10 20 30
+Result: 60
+<help>? multiply 2 5 3
+Result: 30
+<help>? admin-reset
+[command not found - permissions required]
+<help>? 
+```
+
+---
+
+### Example 2 — Multi-Role Access Control
+
+Create an application with different user roles and permissions.
+
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript({
+    perrmissionsKeys: {
+        guest: 0,
+        user: 50,
+        moderator: 100,
+        admin: 999
+    }
+});
+
+// Set initial role
+let currentRole = "guest";
+
+cmd.createCommand({
+    name: "status",
+    description: "Show current role",
+    perms: [cmd.perrmissionsKeys.guest],  // Available to all
+    execute: () => {
+        console.log(`Current role: ${currentRole}`);
+    }
+});
+
+cmd.createCommand({
+    name: "upload",
+    description: "Upload a file",
+    perms: [cmd.perrmissionsKeys.user],   // User and above
+    execute: (args) => {
+        console.log(`Uploading file: ${args[0]}`);
+    }
+});
+
+cmd.createCommand({
+    name: "ban-user",
+    description: "Ban a user",
+    perms: [cmd.perrmissionsKeys.moderator],  // Moderator and above
+    execute: (args) => {
+        console.log(`Banned user: ${args[0]}`);
+    }
+});
+
+cmd.createCommand({
+    name: "login",
+    description: "Login as user",
+    perms: [cmd.perrmissionsKeys.guest],
+    execute: (args) => {
+        if (args[0] === "admin" && args[1] === "password") {
+            currentRole = "admin";
+            cmd.cmdRootPermissions = [cmd.perrmissionsKeys.admin];
+            console.log("Logged in as admin");
+        } else {
+            currentRole = "user";
+            cmd.cmdRootPermissions = [cmd.perrmissionsKeys.user];
+            console.log("Logged in as user");
+        }
+        cmd.updateCommands();
+    }
+});
+
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.guest];
+cmd.updateCommands();
+cmd.Start();
+```
+
+---
+
+### Example 3 — Script File Execution
+
+Execute a BScript file from the command line.
+
+**my-script.js:**
+```javascript
+echo "Script execution started"
+echo "Running calculations..."
+add 5 10
+echo "Done!"
+```
+
+**main.js:**
+```javascript
+const BScript = require("bscript");
+
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+    cmd.perrmissionsKeys.default,
+    cmd.perrmissionsKeys.script
+];
+cmd.updateCommands();
+
+// Execute script file
+const scriptFn = cmd.bscript("script my-script.js");
+scriptFn();
+```
+
+### Run from terminal:
+
+```bash
+node main.js
+```
+
+### Expected output:
+
+```
+Script execution started
+Running calculations...
+[result of add 5 10]
+Done!
+```
+
+---
+
+<a id="6-best-practices"></a>
+
+## 6. Best practices
+
+### 1. Organize Commands in Separate Files
+
+Instead of creating commands in code, create `.js` files in a commands directory:
+
+**commands/echo.js:**
+```javascript
+module.exports = {
+    name: "echo",
+    description: "Echo text",
+    syntax: "echo [text...]",
+    execute: (args) => {
+        console.log(args.join(" "));
+    }
+};
+```
+
+**commands/math/add.js:**
+```javascript
+module.exports = {
+    name: "add",
+    description: "Add numbers",
+    syntax: "add [num1] [num2] ...",
+    execute: (args) => {
+        const sum = args.reduce((a, b) => a + parseFloat(b), 0);
+        console.log(sum);
+    },
+    perms: [0]  // Available to default permission level
+};
+```
+
+### 2. Use Permissions Consistently
+
+Define permission levels early and use them consistently:
+
+```javascript
+const cmd = new BScript({
+    perrmissionsKeys: {
+        public: 0,
+        authenticated: 50,
+        admin: 100
+    }
+});
+```
+
+### 3. Handle Errors Gracefully
+
+Always validate arguments and provide helpful error messages:
+
+```javascript
+cmd.createCommand({
+    name: "divide",
+    execute: (args) => {
+        if (args.length < 2) {
+            console.error("divide: requires 2 arguments");
+            return;
+        }
+        const [a, b] = args.map(parseFloat);
+        if (b === 0) {
+            console.error("divide: cannot divide by zero");
+            return;
+        }
+        console.log(a / b);
+    }
+});
+```
+
+### 4. Use Command Metadata
+
+Provide description and syntax for every command:
+
+```javascript
+cmd.createCommand({
+    name: "user-info",
+    description: "Display user information",
+    syntax: "user-info [username]",
+    execute: (args) => {
+        // Implementation
+    }
+});
+```
+
+### 5. Leverage async/await with Loader
+
+Provide visual feedback for long-running operations:
+
+```javascript
+cmd.createCommand({
+    name: "process-data",
+    execute: () => {
+        cmd.loader(async (done) => {
+            const result = await processLargeDataset();
+            console.log("Processing complete:", result);
+            done();
+        });
+    }
+});
+```
+
+### 6. Keep Command Loading Idempotent
+
+Ensure `updateCommands()` can be called multiple times safely:
+
+```javascript
+// Safe to call after permission changes
+cmd.cmdRootPermissions = [cmd.perrmissionsKeys.admin];
+cmd.updateCommands();  // Re-loads commands with new permissions
+```
+
+### 7. Use Command Aliases for Common Commands
+
+Support multiple names for a single command:
+
+```javascript
+module.exports = {
+    name: ["exit", "quit", "q"],  // Multiple aliases
+    description: "Exit the application",
+    execute: () => {
+        process.exit(0);
+    }
+};
+```
+
+---
+
+<a id="see-also"></a>
+
+## See also
+
+- **[REFERENCE.md](./REFERENCE.md)** — Complete API documentation
+- **[TECHNICAL.md](./TECHNICAL.md)** — Internal architecture
+- **[README.md](./README.md)** — Project overview
+
+---
+
+**Made with ❤️ for the Node.js ecosystem**

package/SRC/BScriptHistory.js

@@ -0,0 +1,98 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+module.exports = class BScriptHistory {
+    constructor(filePath = path.join(os.homedir(), ".bscript_history")) {
+        this.filePath = filePath;
+        this.history = [];
+        this.index = 0;
+
+        this.load();
+    }
+
+    load() {
+        if (!fs.existsSync(this.filePath)) {
+            fs.writeFileSync(this.filePath, "", "utf8");
+            return;
+        }
+
+        const content = fs.readFileSync(this.filePath, "utf8");
+
+        this.history = content
+            .split("\n")
+            .map(x => x.trim())
+            .filter(Boolean);
+
+        this.index = this.history.length;
+    }
+
+    save() {
+        fs.writeFileSync(
+            this.filePath,
+            this.history.join("\n"),
+            "utf8"
+        );
+    }
+
+    add(command) {
+        if (!command?.trim())
+            return;
+
+        if (this.history[this.history.length - 1] === command) {
+            this.index = this.history.length;
+            return;
+        }
+
+        this.history.push(command);
+        this.index = this.history.length;
+
+        this.save();
+    }
+
+    previous() {
+        if (this.index > 0)
+            this.index--;
+
+        return this.history[this.index] ?? "";
+    }
+
+    next() {
+        if (this.index < this.history.length)
+            this.index++;
+
+        return this.history[this.index] ?? "";
+    }
+
+    clear() {
+        this.history = [];
+        this.index = 0;
+
+        this.save();
+    }
+
+    remove(command) {
+        this.history = this.history.filter(x => x !== command);
+
+        if (this.index > this.history.length)
+            this.index = this.history.length;
+
+        this.save();
+    }
+
+    contains(command) {
+        return this.history.includes(command);
+    }
+
+    get(index) {
+        return this.history[index] ?? null;
+    }
+
+    getAll() {
+        return [...this.history];
+    }
+
+    get length() {
+        return this.history.length;
+    }
+}

package/SRC/CMDPermissions.js

@@ -0,0 +1,4 @@
+module.exports = {
+	script: 999,
+	default: 0
+}