starlight-cli 1.1.12 → 1.1.13

package/README.md

@@ -4,417 +4,122 @@
 Starlight is a lightweight, developer-oriented programming language designed for **server-side scripting, automation, and general-purpose programming**. It combines a clean, readable syntax inspired by JavaScript and Python with powerful runtime features such as async/await, modules, and interactive I/O.
 
  **Official Reference:**  
-https://dominexmacedon.github.io/starlight-programming-language/learn.html
-
----
-
-## Key Features
-
-- **Modern, Simple Syntax** – Familiar to JavaScript and Python developers
-- **Async / Await** – Native support for asynchronous operations
-- **Modules & Imports** – Import JavaScript packages or other `.sl` files
-- **Server-side Ready** – Built on Node.js, ideal for backend logic
-- **Interactive I/O** – Built-in `ask` and `sldeploy`
-- **Built-in Utilities** – `sleep`, `len`, `keys`, `values`, `fetch`, `get`, `post`
-
----
-
-## Installation
-
-1. Install **Node.js** (v18+ recommended)
-2. Install the Starlight CLI:
-
-```bash
-npm install -g starlight-cli
-````
-
----
-
-## Your First Program (`hello.sl`)
-
-```sl
-let name = ask("What is your name?")
-sldeploy "Hello, " + name + "!"
-```
-
-Run:
-
-```bash
-starlight hello.sl
-```
-
-### Output
-
-```
-What is your name? Alice
-Hello, Alice!
-```
-
----
-
-## Core Language Concepts
-
-### Variables
-
-```sl
-let x = 10
-let text = "hello"
-```
-
----
-
-### Functions
-
-```sl
-func add(a, b) {
-  return a + b
-}
-
-sldeploy add(2, 3)
-```
-
----
-
-### Async Functions
-
-```sl
-async func load() {
-  let data = await get("https://example.com/api")
-  sldeploy data
-}
-
-load()
-```
-
+https://starlight-programming-language.pages.dev/tutorials
 ---
+## Error Handling in Starlight
 
-## Arrow Functions
+Starlight is designed with **modern, developer-friendly error handling** that clearly explains what went wrong, where it happened, and how to fix it.
 
-Arrow functions provide a **concise and expressive** way to define functions.
+###  Modern Diagnostic Style
 
-### Basic Arrow Function
+Starlight errors follow the same diagnostic standards used by modern languages such as JavaScript, Rust, and Python:
 
-```sl
-let square = x => x * x
-sldeploy square(5)
-```
+- Clear error message
+- Exact **line and column number**
+- Source code preview
+- Visual caret (`^`) pointing to the error location
+- Helpful suggestions when possible
 
-### Multiple Parameters
+Example:
 
-```sl
-let add = (a, b) => a + b
-sldeploy add(10, 20)
 ```
 
-### Block Body with if / else
+Unterminated block
+Did you forget to close the block with '}'?
+at line 5, column 0
 
-```sl
-let label = p => {
-  if (p.price > 1000) {
-    return "Premium"
-  } else {
-    return "Standard"
-  }
-}
 ```
-
-### Arrow Functions with Objects
-
-```sl
-let summarize = p => {
-  return {
-    "name": p.name,
-    "value": p.price * p.stock
-  }
-}
+^
 ```
 
-Arrow functions capture their surrounding scope and behave like standard functions while remaining lightweight and readable.
-
----
-
-## Conditionals
-
-```sl
-if (x > 5) {
-  sldeploy "Greater than 5"
-} else {
-  sldeploy "5 or less"
-}
-```
-
----
-
-## Loops
-
-### While Loop
+````
 
-```sl
-let i = 0
-while (i < 3) {
-  sldeploy i
-  i = i + 1
-}
-```
+This format makes debugging fast and intuitive, even for beginners.
 
 ---
 
-## Start & Race Statements
-
-Starlight includes a **start / race** control structure similar to a switch statement, with **fall-through behavior**.
+### 🧠 Syntax Errors (Parser Errors)
 
-### Syntax
-
-```sl
-start (value) {
-  race (1) {
-    # body
-  }
-
-  race (2) {
-    # body
-  }
-}
-```
+Syntax errors are detected during parsing and reported before execution begins.
 
-### Example
+Features:
+- Precise location tracking
+- Friendly suggestions
+- No Node.js stack traces
+- Clean termination
 
+Example:
 ```sl
-define x = 2
-
-start (x) {
-  race (1) { sldeploy("Race 1 executed") }
-  race (2) { sldeploy("Race 2 executed") }
-  race (3) { sldeploy("Race 3 executed") }
-}
-
-sldeploy("Done with start statement")
-```
-
-### Expected Output
-
-```
-Race 2 executed
-Race 3 executed
-Done with start statement
-```
-
----
-
-## Markdown Preview (`starlight filename.md`)
-
-Starlight can also be used to **preview Markdown files** directly from the CLI.
-
-### Usage
-
-```bash
-starlight README.md
-```
-
-### How It Works (Execution Flow)
-
-1. The CLI detects the `.md` file extension
-2. The Markdown file is read from disk
-3. Markdown is converted to HTML using a full-featured Markdown renderer
-4. A **temporary HTML file** is created in the system temp directory
-5. The file is opened in your default browser using `file://`
-6. After the browser loads, the temporary file is **automatically deleted**
-
-This makes Starlight useful not only as a programming language, but also as a **developer productivity tool**.
-
----
-
-## Array Helpers: map, filter, reduce
-
-Starlight provides built-in **functional helpers** for working with arrays: `map`, `filter`, and `reduce`.  
-These helpers are **async-aware**, work seamlessly with **arrow functions**, and integrate fully with Starlight’s runtime and error handling.
-
-Unlike JavaScript, these are **global functions** (not methods), keeping the language simple and consistent.
-
----
-
-### map(array, fn)
-
-Transforms each element of an array using a callback function and returns a **new array**.
-
-**Syntax:**
-```
-
-map(array, fn)
-
-```
-
-**Example:**
-```
-
-let numbers = [1, 2, 3, 4]
-
-let squared = await map(numbers, x => x * x)
-
-sldeploy squared
-
-```
-
-**Output:**
-```
-
-[ 1, 4, 9, 16 ]
-
-```
-
-- `fn` receives `(value, index, array)`
-- Does **not** modify the original array
-- Supports `async` arrow functions
-
----
-
-### filter(array, fn)
-
-Selects elements from an array that satisfy a condition and returns a **new array**.
-
-**Syntax:**
-```
-
-filter(array, fn)
-
-```
-
-**Example:**
-```
-
-let numbers = [1, 2, 3, 4, 5, 6]
-
-let evens = await filter(numbers, x => x % 2 == 0)
-
-sldeploy evens
+if true {
+  sldeploy("This block is never closed")
+````
 
-```
+Output:
 
-**Output:**
 ```
+Unterminated block
+Did you forget to close the block with '}'?
+  at line 2, column 0
 
-[ 2, 4, 6 ]
-
+    ^
 ```
 
-- `fn` must return `true` or `false`
-- `fn` receives `(value, index, array)`
-- Original array remains unchanged
-
 ---
 
-### reduce(array, fn, initial)
+### ⚙️ Runtime Errors (Evaluator Errors)
 
-Reduces an array to a **single value** by accumulating results using a reducer function.
+Runtime errors occur during execution and include:
 
-**Syntax:**
-```
+* Undefined variables
+* Invalid operations
+* Logical mistakes
 
-reduce(array, fn, initial)
+Starlight also provides **intelligent name suggestions**:
 
 ```
-
-**Example:**
+Undefined variable: "scroe"
+Did you mean "score"?
+  at line 10, column 5
+      ^
 ```
 
-let numbers = [1, 2, 3, 4, 5]
-
-let total = await reduce(numbers, (acc, value) => acc + value, 0)
-
-sldeploy total
-
-```
-
-**Output:**
-```
-
-15
-
-```
-
-- `fn` receives `(accumulator, value, index, array)`
-- `initial` is optional, but recommended
-- Throws a runtime error if used on an empty array without an initial value
-
 ---
 
-### Async Support
-
-All three helpers support `async` functions:
-
-```
-
-let results = await map(items, async item => {
-await sleep(100)
-return item * 2
-})
-
-```
-
----
+### 🎨 Color-Coded Errors
 
-### Why global helpers?
+Errors are color-coded for clarity:
 
-Starlight keeps `map`, `filter`, and `reduce` as **language-level utilities** instead of object methods to:
+* **Red** – Fatal syntax or runtime errors
+* **Yellow** – Warnings or suggestions
+* **White** – Neutral information (source preview, pointers)
 
-- Keep syntax minimal and readable
-- Avoid prototype complexity
-- Work consistently with all iterables
-- Integrate cleanly with the evaluator and runtime
+This ensures errors are readable in all terminals.
 
 ---
 
-### Nullish Coalescing (`??`) Support
+###  Safe Execution Model
 
-Our language now supports the **nullish coalescing operator** `??`, which allows you to provide a default value for `null` or `undefined` expressions.
+* Execution **stops immediately** on error
+* No uncaught exceptions
+* No JavaScript stack traces leaked
+* Clean exit behavior
 
-**Syntax:**
-
-```sl
-value = expression1 ?? expression2
-```
-
-* `expression1` is evaluated first.
-* If it is **not null or undefined**, its value is used.
-* Otherwise, the value of `expression2` is used.
-
-**Example:**
-
-```sl
-define a = null
-define b = a ?? 42
-sldeploy b  # Output: 42
-```
-
-**Notes:**
-
-* Only `null` and `undefined` are treated as "empty" values. Other falsy values like `0`, `false`, or `""` will **not** trigger the default.
-* This operator is optional. If you prefer, you can achieve the same result using a simple `if` statement:
-
-```sl
-define a = null
-define b = if a != null then a else 42
-sldeploy b  # Output: 42
-```
-
-This operator simplifies code that needs default values and makes your scripts cleaner and more readable.
+This keeps Starlight predictable and safe for learning and production use.
 
 ---
 
-## Why Starlight?
+###  Summary
 
-* A **simple but powerful** scripting language
-* **Fast server-side automation**
-* Familiar syntax with **less boilerplate**
-* Full access to the **Node.js ecosystem**
+Starlight’s error handling is:
 
----
+* Modern
+* Precise
+* Beginner-friendly
+* Professional-grade
 
-## License
+By using caret-based diagnostics and intelligent suggestions, Starlight provides a first-class developer experience from day one.
 
-MIT License
 
----
 
 ## Author and Developer
 Dominex Macedon

package/dist/index.js

@@ -10219,65 +10219,76 @@ class ReturnValue {
 }
 class BreakSignal {}
 class ContinueSignal {}
+const COLOR = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  white: '\x1b[37m'
+};
+
 class RuntimeError extends Error {
-    constructor(message, node, source, env = null) {
-        const line = node?.line ?? '?';
-        const column = node?.column ?? '?';
-        let output = ` ${message} at line ${line}, column ${column}\n`;
-
-        if (source && node?.line != null) {
-            const lines = source.split('\n');
-            const srcLine = lines[node.line - 1] || '';
-            output += `  ${srcLine}\n`;
-            const caretPos =
-                typeof column === 'number' && column > 0
-                    ? column - 1
-                    : 0;
-            output += `  ${' '.repeat(caretPos)}^\n`;
-        }
+  constructor(message, node, source, env = null) {
+    const line = node?.line ?? '?';
+    const column = node?.column ?? '?';
 
-        if (env && message.startsWith('Undefined variable:')) {
-            const nameMatch = message.match(/"(.+?)"/);
-            if (nameMatch) {
-                const name = nameMatch[1];
-                const suggestion = RuntimeError.suggest(name, env);
-                if (suggestion) {
-                    output += `Did you mean "${suggestion}"?\n`;
-                }
-            }
-        }
+    let output =
+      `${COLOR.red}${message}${COLOR.reset} at line ${line}, column ${column}\n`;
 
-        super(output);
-        this.name = 'RuntimeError';
-        this.line = line;
-        this.column = column;
+    if (source && node?.line != null) {
+      const lines = source.split('\n');
+      const srcLine = lines[node.line - 1] || '';
+      const caretPos =
+        typeof column === 'number' && column > 0 ? column - 1 : 0;
+
+      output += `${COLOR.white}  ${srcLine}\n`;
+      output += `  ${' '.repeat(caretPos)}^\n${COLOR.reset}`;
+    }
+
+    if (env && message.startsWith('Undefined variable:')) {
+      const nameMatch = message.match(/"(.+?)"/);
+      if (nameMatch) {
+        const name = nameMatch[1];
+        const suggestion = RuntimeError.suggest(name, env);
+        if (suggestion) {
+          output +=
+            `${COLOR.yellow}Did you mean "${suggestion}"?${COLOR.reset}\n`;
+        }
+      }
     }
 
-    static suggest(name, env) {
-        const names = new Set();
-        let current = env;
-        while (current) {
-            for (const key of Object.keys(current.store)) {
-                names.add(key);
-            }
-            current = current.parent;
-        }
+    super(output);
+    this.name = 'RuntimeError';
+    this.line = line;
+    this.column = column;
+  }
 
-        let best = null;
-        let bestScore = Infinity;
+  static suggest(name, env) {
+    const names = new Set();
+    let current = env;
 
-        for (const item of names) {
-            const dist = Math.abs(item.length - name.length) +
-                [...name].filter((c, i) => c !== item[i]).length;
+    while (current) {
+      for (const key of Object.keys(current.store)) {
+        names.add(key);
+      }
+      current = current.parent;
+    }
 
-            if (dist < bestScore && dist <= 2) {
-                bestScore = dist;
-                best = item;
-            }
-        }
+    let best = null;
+    let bestScore = Infinity;
 
-        return best;
+    for (const item of names) {
+      const dist =
+        Math.abs(item.length - name.length) +
+        [...name].filter((c, i) => c !== item[i]).length;
+
+      if (dist < bestScore && dist <= 2) {
+        bestScore = dist;
+        best = item;
+      }
     }
+
+    return best;
+  }
 }
 
 class Environment {
@@ -11835,25 +11846,39 @@ module.exports = Lexer;
 /***/ 222:
 /***/ ((module, __unused_webpack_exports, __nccwpck_require__) => {
 
+const COLOR = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  white: '\x1b[37m'
+};
+
 class ParseError extends Error {
   constructor(message, token, source, suggestion = null) {
     const line = token?.line ?? '?';
     const column = token?.column ?? '?';
 
-    let output = `${message}\n`;
+    let output = `${COLOR.red}${message}${COLOR.reset}\n`;
 
     if (suggestion) {
-      output += `Hint: ${suggestion}\n`;
+      output += `${COLOR.yellow}${suggestion}${COLOR.reset}\n`;
     }
 
     if (source && token?.line != null) {
       const lines = source.split('\n');
       const srcLine = lines[token.line - 1] || '';
-      output += `  at line ${line}, column ${column}\n`;
-      output += `    ${srcLine}\n`;
-      output += `    ${' '.repeat(column - 1)}^\n`;
+
+      output += `${COLOR.white}  at line ${line}, column ${column}\n`;
+      const caretPos =
+  typeof column === 'number' && column > 0
+    ? column - 1
+    : 0;
+
+output += `    ${srcLine}\n`;
+output += `    ${' '.repeat(caretPos)}^\n${COLOR.reset}`;
+
     } else {
-      output += `  at line ${line}, column ${column}\n`;
+      output += `${COLOR.white}  at line ${line}, column ${column}\n${COLOR.reset}`;
     }
 
     super(output);
@@ -11861,7 +11886,6 @@ class ParseError extends Error {
   }
 }
 
-
 class Parser {
   constructor(tokens, source = '') {
   this.tokens = tokens;
@@ -13706,7 +13730,7 @@ const Lexer = __nccwpck_require__(211);
 const Parser = __nccwpck_require__(222);
 const Evaluator = __nccwpck_require__(112);
 
-const VERSION = '1.1.12';
+const VERSION = '1.1.13';
 
 const COLOR = {
     reset: '\x1b[0m',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-cli",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "Starlight Programming Language CLI",
   "bin": {
     "starlight": "index.js"

package/src/evaluator.js

@@ -9,65 +9,76 @@ class ReturnValue {
 }
 class BreakSignal {}
 class ContinueSignal {}
+const COLOR = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  white: '\x1b[37m'
+};
+
 class RuntimeError extends Error {
-    constructor(message, node, source, env = null) {
-        const line = node?.line ?? '?';
-        const column = node?.column ?? '?';
-        let output = ` ${message} at line ${line}, column ${column}\n`;
-
-        if (source && node?.line != null) {
-            const lines = source.split('\n');
-            const srcLine = lines[node.line - 1] || '';
-            output += `  ${srcLine}\n`;
-            const caretPos =
-                typeof column === 'number' && column > 0
-                    ? column - 1
-                    : 0;
-            output += `  ${' '.repeat(caretPos)}^\n`;
-        }
+  constructor(message, node, source, env = null) {
+    const line = node?.line ?? '?';
+    const column = node?.column ?? '?';
 
-        if (env && message.startsWith('Undefined variable:')) {
-            const nameMatch = message.match(/"(.+?)"/);
-            if (nameMatch) {
-                const name = nameMatch[1];
-                const suggestion = RuntimeError.suggest(name, env);
-                if (suggestion) {
-                    output += `Did you mean "${suggestion}"?\n`;
-                }
-            }
-        }
+    let output =
+      `${COLOR.red}${message}${COLOR.reset} at line ${line}, column ${column}\n`;
+
+    if (source && node?.line != null) {
+      const lines = source.split('\n');
+      const srcLine = lines[node.line - 1] || '';
+      const caretPos =
+        typeof column === 'number' && column > 0 ? column - 1 : 0;
 
-        super(output);
-        this.name = 'RuntimeError';
-        this.line = line;
-        this.column = column;
+      output += `${COLOR.white}  ${srcLine}\n`;
+      output += `  ${' '.repeat(caretPos)}^\n${COLOR.reset}`;
     }
 
-    static suggest(name, env) {
-        const names = new Set();
-        let current = env;
-        while (current) {
-            for (const key of Object.keys(current.store)) {
-                names.add(key);
-            }
-            current = current.parent;
+    if (env && message.startsWith('Undefined variable:')) {
+      const nameMatch = message.match(/"(.+?)"/);
+      if (nameMatch) {
+        const name = nameMatch[1];
+        const suggestion = RuntimeError.suggest(name, env);
+        if (suggestion) {
+          output +=
+            `${COLOR.yellow}Did you mean "${suggestion}"?${COLOR.reset}\n`;
         }
+      }
+    }
 
-        let best = null;
-        let bestScore = Infinity;
+    super(output);
+    this.name = 'RuntimeError';
+    this.line = line;
+    this.column = column;
+  }
 
-        for (const item of names) {
-            const dist = Math.abs(item.length - name.length) +
-                [...name].filter((c, i) => c !== item[i]).length;
+  static suggest(name, env) {
+    const names = new Set();
+    let current = env;
 
-            if (dist < bestScore && dist <= 2) {
-                bestScore = dist;
-                best = item;
-            }
-        }
+    while (current) {
+      for (const key of Object.keys(current.store)) {
+        names.add(key);
+      }
+      current = current.parent;
+    }
+
+    let best = null;
+    let bestScore = Infinity;
+
+    for (const item of names) {
+      const dist =
+        Math.abs(item.length - name.length) +
+        [...name].filter((c, i) => c !== item[i]).length;
 
-        return best;
+      if (dist < bestScore && dist <= 2) {
+        bestScore = dist;
+        best = item;
+      }
     }
+
+    return best;
+  }
 }
 
 class Environment {

package/src/parser.js

@@ -1,22 +1,36 @@
+const COLOR = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  white: '\x1b[37m'
+};
+
 class ParseError extends Error {
   constructor(message, token, source, suggestion = null) {
     const line = token?.line ?? '?';
     const column = token?.column ?? '?';
 
-    let output = `${message}\n`;
+    let output = `${COLOR.red}${message}${COLOR.reset}\n`;
 
     if (suggestion) {
-      output += `Hint: ${suggestion}\n`;
+      output += `${COLOR.yellow}${suggestion}${COLOR.reset}\n`;
     }
 
     if (source && token?.line != null) {
       const lines = source.split('\n');
       const srcLine = lines[token.line - 1] || '';
-      output += `  at line ${line}, column ${column}\n`;
-      output += `    ${srcLine}\n`;
-      output += `    ${' '.repeat(column - 1)}^\n`;
+
+      output += `${COLOR.white}  at line ${line}, column ${column}\n`;
+      const caretPos =
+  typeof column === 'number' && column > 0
+    ? column - 1
+    : 0;
+
+output += `    ${srcLine}\n`;
+output += `    ${' '.repeat(caretPos)}^\n${COLOR.reset}`;
+
     } else {
-      output += `  at line ${line}, column ${column}\n`;
+      output += `${COLOR.white}  at line ${line}, column ${column}\n${COLOR.reset}`;
     }
 
     super(output);
@@ -24,7 +38,6 @@ class ParseError extends Error {
   }
 }
 
-
 class Parser {
   constructor(tokens, source = '') {
   this.tokens = tokens;

package/src/starlight.js

@@ -12,7 +12,7 @@ const Lexer = require('./lexer');
 const Parser = require('./parser');
 const Evaluator = require('./evaluator');
 
-const VERSION = '1.1.12';
+const VERSION = '1.1.13';
 
 const COLOR = {
     reset: '\x1b[0m',