bscript-cli 1.0.0

package/Docs/TECHNICAL.md

@@ -0,0 +1,1143 @@
+# Technical Documentation
+
+This document describes the complete internal architecture of the library, including **public and internal modules, classes, functions, constants, and helper utilities**.
+
+Public declarations are also documented in **REFERENCE.md**, while this document contains implementation details intended primarily for contributors and maintainers.
+
+---
+
+## Guide
+
+<details>
+<summary>BScript</summary>
+
+## Parent
+[BScript.BScript](#BScriptBScript)
+
+### Constants
+- [perrmissionsKeys](#BScriptBScriptperrmissionsKeys)
+
+### Properties
+- [cmdRootPermissions](#BScriptBScriptcmdRootPermissions)
+- [commandHistory](#BScriptBScriptcommandHistory)
+- [returnCode](#BScriptBScriptreturnCode)
+- [_commands](#BScriptBScript_commands)
+- [_commandHistoryLimit](#BScriptBScript_commandHistoryLimit)
+- [_historyPos](#BScriptBScript_historyPos)
+
+### Methods
+- [bscript()](#BScriptBScriptbscript)
+- [Start()](#BScriptBScriptStart)
+- [updateCommands()](#BScriptBScriptupdateCommands)
+- [createCommand()](#BScriptBScriptcreateCommand)
+- [executeCommand()](#BScriptBScriptexecuteCommand)
+- [loader()](#BScriptBScriptloader)
+- [pushToCommandHistory()](#BScriptBScriptpushToCommandHistory)
+
+</details>
+
+<details>
+<summary>TerminalCommandController</summary>
+
+## Parent
+[TerminalCommandController.TCC](#TerminalCommandControllerTCC)
+
+### Properties
+- [stdinVal](#TerminalCommandControllerTCCstdinVal)
+- [col](#TerminalCommandControllerTCCcol)
+- [BScriptHistory](#TerminalCommandControllerTCCBScriptHistory)
+
+### Methods
+- [ClearLine()](#TerminalCommandControllerTCCClearLine)
+- [CursorTo()](#TerminalCommandControllerTCCCursorTo)
+- [WriteCommand()](#TerminalCommandControllerTCCWriteCommand)
+- [commandRender()](#TerminalCommandControllerTCCcommandRender)
+- [OnData()](#TerminalCommandControllerTCCOnData)
+
+</details>
+
+<details>
+<summary>BScriptHistory</summary>
+
+## Parent
+[BScriptHistory.BScriptHistory](#BScriptHistoryBScriptHistory)
+
+### Methods
+- [load()](#BScriptHistoryload)
+- [save()](#BScriptHistorysave)
+- [clear()](#BScriptHistoryclear)
+
+</details>
+
+<details>
+<summary>Utilities</summary>
+
+## Parent
+[Utilities.utils](#Utilitiesutils)
+
+### Functions
+- [readDirRecursive()](#Utilitiesreadfilerecursive)
+- [getLeftWordIndex()](#UtilitiesgetLeftWordIndex)
+- [getRightWordIndex()](#UtilitiesgetRightWordIndex)
+- [delay()](#Utilitiesdelay)
+- [arraysIsEqual()](#UtilitiesarraysIsEqual)
+- [insert()](#Utilitiesinsert)
+- [removeByIndex()](#UtilitiesremoveByIndex)
+
+</details>
+
+---
+
+<a id="BScriptBScript"></a>
+
+## BScript.BScript
+
+[REFERENCE.md](./REFERENCE.md#BScriptBScript)
+
+### Opportunities
+
+- Support for asynchronous command execution with loader animations
+- Custom sandbox contexts for safe script evaluation
+- Hot-reload of commands without process restart
+- Event-driven architecture for extensibility
+- Fine-grained permission system for multi-role applications
+- Integration with external command loaders
+
+### Declaration
+
+```javascript
+class BScript extends EventEmitter
+```
+
+Core command-line interface engine that manages command registration, execution, permissions, and terminal interaction.
+
+---
+
+## Constants
+
+<table>
+
+<tr>
+<th>Constant</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptperrmissionsKeys"></a>
+
+<td>
+
+<code>perrmissionsKeys</code>
+
+</td>
+
+<td>
+
+```javascript
+const perrmissionsKeys = {
+  default: 0,
+  script: 999,
+  ...options.perrmissionsKeys
+}
+```
+
+</td>
+
+<td>
+
+Permission level constants merged from CMDPermissions and constructor options. Defines access control tiers for commands.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+## Properties
+
+<table>
+
+<tr>
+<th>Property</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptcmdRootPermissions"></a>
+
+<td>
+
+<code>cmdRootPermissions</code>
+
+</td>
+
+<td>
+
+```javascript
+this.cmdRootPermissions = [
+  ...options.cmdRootPermissions ?? []
+]
+```
+
+</td>
+
+<td>
+
+Array of current permission levels. Controls which commands are available. Modified to change access levels.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptcommandHistory"></a>
+
+<td>
+
+<code>commandHistory</code>
+
+</td>
+
+<td>
+
+```javascript
+this.commandHistory = []
+```
+
+</td>
+
+<td>
+
+List of executed commands. Persisted through BScriptHistory. Limited to _commandHistoryLimit entries.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptreturnCode"></a>
+
+<td>
+
+<code>returnCode</code>
+
+</td>
+
+<td>
+
+```javascript
+this.returnCode = 1
+```
+
+</td>
+
+<td>
+
+Exit status code. -1 = loading, 1 = ready, other values indicate errors or custom states.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScript_commands"></a>
+
+<td>
+
+<code>_commands</code>
+
+</td>
+
+<td>
+
+```javascript
+this._commands = {}
+```
+
+</td>
+
+<td>
+
+Internal registry of loaded commands. Keyed by command name, values contain execute functions and metadata.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScript_commandHistoryLimit"></a>
+
+<td>
+
+<code>_commandHistoryLimit</code>
+
+</td>
+
+<td>
+
+```javascript
+this._commandHistoryLimit = 10
+```
+
+</td>
+
+<td>
+
+Maximum number of commands to retain in history. Oldest entries are removed when limit exceeded.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScript_historyPos"></a>
+
+<td>
+
+<code>_historyPos</code>
+
+</td>
+
+<td>
+
+```javascript
+this._historyPos = -1
+```
+
+</td>
+
+<td>
+
+Current position in command history during navigation. -1 = no history entry selected.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+## Methods
+
+<table>
+
+<tr>
+<th>Method</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptbscript"></a>
+
+<td>
+
+<code>bscript()</code>
+
+</td>
+
+<td>
+
+```javascript
+bscript(scriptCode)
+```
+
+</td>
+
+<td>
+
+Parses a script string and returns a function that executes it. Uses BScriptRunner for parsing. Supports script paths and inline code.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptStart"></a>
+
+<td>
+
+<code>Start()</code>
+
+</td>
+
+<td>
+
+```javascript
+Start()
+```
+
+</td>
+
+<td>
+
+Initializes raw mode input, sets up stdin listeners, and begins the interactive command loop. Displays prompt and processes user input in real-time.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptupdateCommands"></a>
+
+<td>
+
+<code>updateCommands()</code>
+
+</td>
+
+<td>
+
+```javascript
+updateCommands()
+```
+
+</td>
+
+<td>
+
+Scans all commandsPaths directories for .js files. Loads each file in isolated sandbox with vm.runInNewContext. Filters based on permissions and command properties.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptcreateCommand"></a>
+
+<td>
+
+<code>createCommand()</code>
+
+</td>
+
+<td>
+
+```javascript
+createCommand({
+  name,
+  execute,
+  description,
+  syntax,
+  uniqueKey
+})
+```
+
+</td>
+
+<td>
+
+Registers a command in \_commands. Supports command aliases (multiple names). Stores metadata for help and introspection.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptexecuteCommand"></a>
+
+<td>
+
+<code>executeCommand()</code>
+
+</td>
+
+<td>
+
+```javascript
+executeCommand(commandString)
+```
+
+</td>
+
+<td>
+
+Parses command string into command name and arguments. Looks up command in registry and invokes execute function with arguments array.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptloader"></a>
+
+<td>
+
+<code>loader()</code>
+
+</td>
+
+<td>
+
+```javascript
+loader(func)
+```
+
+</td>
+
+<td>
+
+Async wrapper that displays animated "Loading..." message while executing function. Calls done() callback when complete. Sets returnCode to -1 during loading, 1 when done.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptBScriptpushToCommandHistory"></a>
+
+<td>
+
+<code>pushToCommandHistory()</code>
+
+</td>
+
+<td>
+
+```javascript
+pushToCommandHistory(cmd)
+```
+
+</td>
+
+<td>
+
+Adds command to history if not duplicate of last entry. Removes oldest entry if history exceeds \_commandHistoryLimit.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+<a id="TerminalCommandControllerTCC"></a>
+
+## TerminalCommandController.TCC
+
+### Declaration
+
+```javascript
+class TCC
+```
+
+Low-level terminal controller managing stdin/stdout operations, cursor control, and raw input processing. Integrates with BScriptHistory for persistence.
+
+---
+
+## Properties
+
+<table>
+
+<tr>
+<th>Property</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCstdinVal"></a>
+
+<td>
+
+<code>stdinVal</code>
+
+</td>
+
+<td>
+
+```javascript
+this.stdinVal = args?.defaultCommandPrefix ?? 0
+```
+
+</td>
+
+<td>
+
+Current value of stdin/command line buffer. Updated as user types.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCcol"></a>
+
+<td>
+
+<code>col</code>
+
+</td>
+
+<td>
+
+```javascript
+this.col = args?.col ?? 0
+```
+
+</td>
+
+<td>
+
+Current cursor column position relative to command prefix. Used for accurate cursor positioning during editing.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCBScriptHistory"></a>
+
+<td>
+
+<code>BScriptHistory</code>
+
+</td>
+
+<td>
+
+```javascript
+this.BScriptHistory = new BScriptHistory()
+```
+
+</td>
+
+<td>
+
+Instance of BScriptHistory for managing persistent command history. Synced on exit via signal handlers.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+## Methods
+
+<table>
+
+<tr>
+<th>Method</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCClearLine"></a>
+
+<td>
+
+<code>ClearLine()</code>
+
+</td>
+
+<td>
+
+```javascript
+ClearLine()
+```
+
+</td>
+
+<td>
+
+Sends ANSI escape sequence to clear current line and move cursor to beginning. Uses "\r\x1b[K".
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCCursorTo"></a>
+
+<td>
+
+<code>CursorTo()</code>
+
+</td>
+
+<td>
+
+```javascript
+CursorTo(pos)
+```
+
+</td>
+
+<td>
+
+Positions cursor at absolute column position using stdout.cursorTo().
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCWriteCommand"></a>
+
+<td>
+
+<code>WriteCommand()</code>
+
+</td>
+
+<td>
+
+```javascript
+WriteCommand(cmd)
+```
+
+</td>
+
+<td>
+
+Writes command with prefix prompt. Combines defaultCommandPrefix with command text.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCcommandRender"></a>
+
+<td>
+
+<code>commandRender()</code>
+
+</td>
+
+<td>
+
+```javascript
+commandRender(inputStdin)
+```
+
+</td>
+
+<td>
+
+Core input handler processing single keypress. Handles arrow keys, delete, backspace, history navigation, word jumping. Returns 1 for Enter, 0 otherwise.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="TerminalCommandControllerTCCOnData"></a>
+
+<td>
+
+<code>OnData()</code>
+
+</td>
+
+<td>
+
+```javascript
+OnData(inputStdin)
+```
+
+</td>
+
+<td>
+
+Public wrapper for commandRender(). Called by stdin 'data' event listener.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+<a id="BScriptHistoryBScriptHistory"></a>
+
+## BScriptHistory.BScriptHistory
+
+### Declaration
+
+```javascript
+class BScriptHistory
+```
+
+Manages persistent command history stored on disk. Loads history on instantiation and provides save/load/clear interface.
+
+---
+
+## Methods
+
+<table>
+
+<tr>
+<th>Method</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="BScriptHistoryload"></a>
+
+<td>
+
+<code>load()</code>
+
+</td>
+
+<td>
+
+```javascript
+load()
+```
+
+</td>
+
+<td>
+
+Reads history file from disk and parses it. Called automatically in constructor. Returns array of command strings.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptHistorysave"></a>
+
+<td>
+
+<code>save()</code>
+
+</td>
+
+<td>
+
+```javascript
+save()
+```
+
+</td>
+
+<td>
+
+Writes current history array to persistent storage. Called on process exit and SIGINT/SIGTERM signals.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="BScriptHistoryclear"></a>
+
+<td>
+
+<code>clear()</code>
+
+</td>
+
+<td>
+
+```javascript
+clear()
+```
+
+</td>
+
+<td>
+
+Clears in-memory history and deletes history file. Useful for starting fresh sessions.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+<a id="Utilitiesutils"></a>
+
+## Utilities.utils
+
+### Declaration
+
+```javascript
+module.exports = {
+  readDirRecursive,
+  getLeftWordIndex,
+  getRightWordIndex,
+  delay,
+  arraysIsEqual,
+  insert,
+  removeByIndex
+}
+```
+
+Collection of utility functions used throughout the codebase for file scanning, text manipulation, and timing.
+
+---
+
+## Functions
+
+<table>
+
+<tr>
+<th>Function</th>
+<th>Declaration</th>
+<th>Description</th>
+</tr>
+
+<tr>
+
+<a id="Utilitiesreadfilerecursive"></a>
+
+<td>
+
+<code>readDirRecursive()</code>
+
+</td>
+
+<td>
+
+```javascript
+readDirRecursive(dir)
+```
+
+</td>
+
+<td>
+
+Recursively scans directory and returns array of all file paths (not directories). Used by updateCommands() to find .js files.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="UtilitiesgetLeftWordIndex"></a>
+
+<td>
+
+<code>getLeftWordIndex()</code>
+
+</td>
+
+<td>
+
+```javascript
+getLeftWordIndex(text, index)
+```
+
+</td>
+
+<td>
+
+Returns character index of start of word to the left of cursor position. Handles edge cases at text boundaries.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="UtilitiesgetRightWordIndex"></a>
+
+<td>
+
+<code>getRightWordIndex()</code>
+
+</td>
+
+<td>
+
+```javascript
+getRightWordIndex(text, index)
+```
+
+</td>
+
+<td>
+
+Returns character index of end of word to the right of cursor position.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="Utilitiesdelay"></a>
+
+<td>
+
+<code>delay()</code>
+
+</td>
+
+<td>
+
+```javascript
+delay(time)
+```
+
+</td>
+
+<td>
+
+Promise-based delay for async/await. Resolves after specified milliseconds. Used in loader animation.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="UtilitiesarraysIsEqual"></a>
+
+<td>
+
+<code>arraysIsEqual()</code>
+
+</td>
+
+<td>
+
+```javascript
+arraysIsEqual(arr1, arr2)
+```
+
+</td>
+
+<td>
+
+Compares two arrays by JSON serialization. Returns true if contents are identical.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="Utilitiesinsert"></a>
+
+<td>
+
+<code>insert()</code>
+
+</td>
+
+<td>
+
+```javascript
+insert(str, index, string)
+```
+
+</td>
+
+<td>
+
+Inserts substring at specified index. Returns modified string.
+
+</td>
+
+</tr>
+
+<tr>
+
+<a id="UtilitiesremoveByIndex"></a>
+
+<td>
+
+<code>removeByIndex()</code>
+
+</td>
+
+<td>
+
+```javascript
+removeByIndex(str, index)
+```
+
+</td>
+
+<td>
+
+Removes character at specified index. Used for backspace/delete key handling.
+
+</td>
+
+</tr>
+
+</table>
+
+---
+
+## Internal Architecture Notes
+
+### Command Loading Pipeline
+
+1. `updateCommands()` called with configured permission levels
+2. Scans all commandsPaths directories recursively for .js files
+3. For each file, creates isolated V8 context using `vm.runInNewContext()`
+4. File executed in sandbox with access to CMDPermissions, require, and globals
+5. Module exports checked for command definition properties
+6. Permission filtering applied: command must have matching perms, no excludePerms
+7. Command(s) registered via `createCommand()`
+
+### Permission System
+
+- Commands define required permissions via `.perms` array
+- Commands can exclude certain permissions via `.excludePerms` array
+- Root permissions (`cmdRootPermissions`) combined with history permissions (`cmdPermissionsHistory`)
+- Permission check: `cmdPermission.some(currentPerm => command.perms.includes(currentPerm))`
+
+### Async Loader Pattern
+
+- `loader(func)` provides animation while async work completes
+- Returns Promise that resolves when done() callback invoked
+- Three parameters: `done()` to finish, `waitForPromise()` for nested async, `startAnimation()` to restart
+
+### Terminal Input Handling
+
+- Raw mode enabled via stdin.setRawMode(true)
+- Each keystroke triggers `OnData()` with character code
+- Arrow keys sent as multi-byte escape sequences (e.g., "\u001b[A" for up)
+- History navigation modifies stdinVal and updates display
+- Word boundary detection via helper functions for Ctrl+Left/Right
+
+---
+
+**Made with ❤️ for the Node.js ecosystem**