nebulara 2.0.0

package/SPEC.md

@@ -0,0 +1,267 @@
+# Nebulara Language Specification v3.0
+
+## File Extension
+`.nbs` - Nebulara Source
+
+## Comments
+```
+# This is a line comment
+```
+
+## Keywords
+
+| Keyword | Usage | Example |
+|---------|-------|---------|
+| `FUNC!` | Define function | `FUNC! add(a, b):` |
+| `END!` | Block end | `END!` |
+| `LET` | Variable declaration | `LET x = 10` |
+| `CONST` | Constant declaration | `CONST PI = 314` |
+| `IF?` | Conditional | `IF? x > 10:` |
+| `ELSE` | Else branch | `ELSE:` |
+| `ELSEIF?` | Else-if branch | `ELSEIF? x > 5:` |
+| `WHILE?` | While loop | `WHILE? i < 10:` |
+| `FOR!` | For loop | `FOR! i = 1 TO 10:` |
+| `TO` | FOR loop range | `FOR! i = 1 TO 10:` |
+| `STEP` | FOR loop step | `FOR! i = 0 TO 20 STEP 5:` |
+| `RETURN` | Return value | `RETURN a + b` |
+| `BREAK` | Exit loop | `BREAK` |
+| `CONTINUE` | Skip iteration | `CONTINUE` |
+| `TRY` | Try block | `TRY:` |
+| `CATCH` | Catch block | `CATCH err:` |
+| `THROW` | Throw exception | `THROW "error"` |
+| `AND` | Logical AND | `IF? a AND b:` |
+| `OR` | Logical OR | `IF? a OR b:` |
+| `NOT` | Logical NOT | `IF? NOT done:` |
+| `TRUE` | Boolean true | `LET x = TRUE` |
+| `FALSE` | Boolean false | `LET x = FALSE` |
+| `NULL` | Null value | `IF? x == NULL:` |
+
+## Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| Int | 64-bit signed integer | `42`, `-7` |
+| String | UTF-8 text | `"hello"` |
+| Bool | Boolean | `TRUE`, `FALSE` |
+| Array | Dynamic list | `[1, 2, 3]` |
+| Null | Absence of value | `NULL` |
+| Func | Function reference | `FUNC! name():` |
+
+## Syntax
+
+### Variable Declaration
+```
+LET x = 10
+LET name = "Nebulara"
+LET arr = [1, 2, 3]
+x = 20               # reassignment (no LET)
+```
+
+### Function Definition
+```
+FUNC! add(a, b):
+  RETURN a + b
+END!
+
+FUNC! greet(name):
+  PRINT "Hello " + name
+END!
+
+FUNC! noArgs():
+  PRINT "no parameters"
+END!
+```
+
+### Function Call
+```
+PRINT add(3, 4)        # prints 7
+greet("World")          # prints "Hello World"
+```
+
+### Control Flow
+
+#### If/Else
+```
+IF? x > 10:
+  PRINT "big"
+ELSEIF? x > 5:
+  PRINT "medium"
+ELSE:
+  PRINT "small"
+END!
+```
+
+#### While Loop
+```
+LET i = 1
+WHILE? i <= 5:
+  PRINT i
+  i = i + 1
+END!
+```
+
+#### For Loop
+```
+FOR! i = 1 TO 5:
+  PRINT i
+END!
+
+# With STEP
+FOR! i = 0 TO 20 STEP 5:
+  PRINT i
+END!
+```
+
+#### Try/Catch/Throw
+```
+TRY:
+  LET x = TO_NUMBER("not a number")
+CATCH err:
+  PRINT "Error: " + err
+END!
+```
+
+`THROW` raises an exception with a value (typically a string). If no `TRY` block is active, the program terminates with an uncaught exception error.
+
+### Operators
+
+#### Arithmetic
+```
++   # addition / string concatenation
+-   # subtraction
+*   # multiplication
+/   # division
+%   # modulo
+-   # unary negation
+```
+
+#### Bitwise
+```
+&   # bitwise AND: 5 & 3 → 1
+|   # bitwise OR:  5 | 3 → 7
+<<  # left shift:  1 << 3 → 8
+>>  # right shift:  8 >> 2 → 2
+```
+
+#### Comparison
+```
+==  # equal
+!=  # not equal
+<   # less than
+>   # greater than
+<=  # less or equal
+>=  # greater or equal
+```
+
+#### Logical
+```
+AND  # logical and
+OR   # logical or
+NOT  # logical not
+```
+
+#### String
+```
++   # concatenation: "hello" + " " + "world" → "hello world"
+```
+
+### Arrays
+```
+LET arr = [10, 20, 30]
+PRINT arr[0]         # 10
+arr[1] = 99          # mutation: arr is now [10, 99, 30]
+PRINT LEN(arr)       # 3
+```
+
+Arrays support index-based assignment (`arr[i] = value`) to mutate elements in place.
+
+### Built-in Functions
+
+#### Output & Input
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `PRINT` | `PRINT(value)` | Print value to stdout with newline. Accepts any type. |
+
+#### String Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `LEN` | `LEN(value)` | Returns the length of a string (byte count) or array (element count). Returns `0` for other types. |
+| `TYPEOF` | `TYPEOF(value)` | Returns the type name as a string: `"int"`, `"string"`, `"bool"`, `"array"`, `"null"`, `"func"` |
+| `TO_STRING` | `TO_STRING(value)` | Convert value to its string representation. |
+| `TO_NUMBER` | `TO_NUMBER(value)` | Parse a string as an integer (`atoll`). Returns `0` for non-parseable strings. Returns the value unchanged if already an int. |
+| `CHAR_AT` | `CHAR_AT(str, index)` | Returns the single-character string at `index`. Returns `NULL` if index is out of bounds. |
+| `SUBSTR` | `SUBSTR(str, start, length)` | Returns a substring starting at `start` for `length` characters. Clamps to string bounds. |
+| `TRIM` | `TRIM(str)` | Removes leading and trailing whitespace (spaces, tabs, newlines, carriage returns). |
+| `TO_UPPER` | `TO_UPPER(str)` | Returns an uppercase copy of the string. Returns `""` for non-strings. |
+| `TO_LOWER` | `TO_LOWER(str)` | Returns a lowercase copy of the string. Returns `""` for non-strings. |
+| `CHAR` | `CHAR(code)` | Convert an integer code point to a single-character string. |
+| `ORD` | `ORD(char)` | Convert the first character of a string to its integer code point. Returns `0` for empty strings. |
+
+#### Math Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `ABS` | `ABS(n)` | Absolute value. Returns `0` for non-integers. |
+| `MIN` | `MIN(a, b)` | Returns the smaller of two integers. |
+| `MAX` | `MAX(a, b)` | Returns the larger of two integers. |
+| `SQRT` | `SQRT(n)` | Integer square root (truncated). |
+| `POW` | `POW(base, exp)` | Integer power: `base` raised to `exp`. |
+| `FLOOR` | `FLOOR(n)` | Floor (no-op on integers, passes value through). |
+| `CEIL` | `CEIL(n)` | Ceiling (no-op on integers, passes value through). |
+| `ROUND` | `ROUND(n)` | Round (no-op on integers, passes value through). |
+| `RANDOM` | `RANDOM()` | Returns a random integer from `0` to `99`. |
+
+#### Array Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `PUSH` | `PUSH(arr, value)` | Appends `value` to the end of `arr`. Returns the modified array. |
+| `POP` | `POP(arr)` | Removes and returns the last element. Returns `NULL` if the array is empty. |
+
+#### System Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `TIME` | `TIME()` | Returns the current epoch time in seconds. |
+| `READ_FILE` | `READ_FILE(path)` | Reads and returns the entire contents of a file as a string. Returns `NULL` if the file cannot be opened. |
+| `WRITE_FILE` | `WRITE_FILE(path, content)` | Writes `content` to the file at `path`. Returns `TRUE` on success, `FALSE` on failure. |
+
+## Example Programs
+
+### Factorial
+```
+FUNC! factorial(n):
+  IF? n <= 1:
+    RETURN 1
+  END!
+  RETURN n * factorial(n - 1)
+END!
+
+PRINT factorial(5)    # 120
+PRINT factorial(10)   # 3628800
+```
+
+### Array Mutation
+```
+LET arr = [1, 2, 3]
+PUSH(arr, 4)
+PRINT arr             # [1, 2, 3, 4]
+arr[0] = 99
+PRINT arr             # [99, 2, 3, 4]
+PRINT POP(arr)        # 4
+PRINT arr             # [99, 2, 3]
+```
+
+### Try/Catch
+```
+TRY:
+  LET result = TO_NUMBER("not a number")
+  IF? result == 0:
+    THROW "parse failed"
+  END!
+CATCH err:
+  PRINT err
+END!
+```

package/bin/neb.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const exeName = process.platform === 'win32' ? 'nebulara.exe' : 'nebulara';
+
+// Try to find the native binary
+function findBinary() {
+    // In installed package: bin/../build/
+    const pkgRoot = path.resolve(__dirname, '..');
+    const candidates = [
+        path.join(pkgRoot, 'build', exeName),
+        path.join(pkgRoot, exeName),
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p)) return p;
+    }
+    return null;
+}
+
+const bin = findBinary();
+if (!bin) {
+    console.error('Error: Nebulara binary not found. Run "npm run build" first.');
+    process.exit(1);
+}
+
+try {
+    execFileSync(bin, args, { stdio: 'inherit' });
+} catch (err) {
+    if (err.status !== undefined) process.exit(err.status);
+    process.exit(1);
+}

package/dist/index.js

@@ -0,0 +1,131 @@
+/**
+ * @codurra/nebulara - Nebulara Programming Language Runtime
+ * 
+ * Provides programmatic access to the Nebulara interpreter, transpiler, and compiler.
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const BUILD_DIR = path.join(__dirname, '..', 'build');
+const PLATFORM = os.platform();
+const EXTENSION = PLATFORM === 'win32' ? '.exe' : '';
+
+const INTERPRETER = path.join(BUILD_DIR, `nebulara${EXTENSION}`);
+const CLI = path.join(BUILD_DIR, `neb-cli${EXTENSION}`);
+const PIPELINE = path.join(BUILD_DIR, `neb-pipeline${EXTENSION}`);
+
+/**
+ * Run a Nebulara source file
+ * @param {string} sourcePath - Path to .nbs file
+ * @param {object} options - { debug: boolean }
+ * @returns {string} stdout output
+ */
+function run(sourcePath, options = {}) {
+    if (!fs.existsSync(sourcePath)) throw new Error(`Source file not found: ${sourcePath}`);
+    const args = [sourcePath];
+    if (options.debug) args.unshift('-d');
+    return execFileSync(INTERPRETER, args, { encoding: 'utf8', timeout: 30000 });
+}
+
+/**
+ * Run a Nebulara source string
+ * @param {string} source - Nebulara source code
+ * @param {object} options - { debug: boolean }
+ * @returns {string} stdout output
+ */
+function runString(source, options = {}) {
+    const tmpFile = path.join(os.tmpdir(), `neb_${Date.now()}.nbs`);
+    try {
+        fs.writeFileSync(tmpFile, source, 'utf8');
+        return run(tmpFile, options);
+    } finally {
+        try { fs.unlinkSync(tmpFile); } catch (e) {}
+    }
+}
+
+/**
+ * Transpile Nebulara to JavaScript
+ * @param {string} sourcePath - Path to .nbs file
+ * @returns {string} Transpiled JavaScript code
+ */
+function transpileToJS(sourcePath) {
+    if (!fs.existsSync(PIPELINE)) throw new Error('Pipeline binary not found. Run "npm run build" first.');
+    return execFileSync(PIPELINE, [sourcePath, '--target', 'js'], { encoding: 'utf8' });
+}
+
+/**
+ * Transpile Nebulara to Python
+ * @param {string} sourcePath - Path to .nbs file
+ * @returns {string} Transpiled Python code
+ */
+function transpileToPython(sourcePath) {
+    if (!fs.existsSync(PIPELINE)) throw new Error('Pipeline binary not found. Run "npm run build" first.');
+    return execFileSync(PIPELINE, [sourcePath, '--target', 'py'], { encoding: 'utf8' });
+}
+
+/**
+ * Check if a .nbs file parses correctly
+ * @param {string} sourcePath - Path to .nbs file
+ * @returns {{ ok: boolean, output: string }}
+ */
+function check(sourcePath) {
+    if (!fs.existsSync(PIPELINE)) throw new Error('Pipeline binary not found. Run "npm run build" first.');
+    try {
+        const output = execFileSync(PIPELINE, [sourcePath], { encoding: 'utf8' });
+        return { ok: true, output: output.trim() };
+    } catch (e) {
+        return { ok: false, output: (e.stderr || e.message).trim() };
+    }
+}
+
+/**
+ * Get the language specification
+ * @returns {string} SPEC.md content
+ */
+function getSpec() {
+    return fs.readFileSync(path.join(__dirname, '..', 'SPEC.md'), 'utf8');
+}
+
+/**
+ * Run the built-in test suite
+ * @returns {{ passed: number, failed: number, results: object[] }}
+ */
+function test() {
+    const testDir = path.join(__dirname, '..', 'test');
+    const results = [];
+    let passed = 0, failed = 0;
+    const testFiles = fs.readdirSync(testDir).filter(f => f.endsWith('.nbs'));
+    for (const file of testFiles) {
+        try {
+            const output = run(path.join(testDir, file));
+            results.push({ file, status: 'pass', output: output.trim() });
+            passed++;
+        } catch (e) {
+            results.push({ file, status: 'fail', error: e.message });
+            failed++;
+        }
+    }
+    return { passed, failed, results };
+}
+
+/**
+ * Check if the Nebulara binary is available
+ * @returns {boolean}
+ */
+function isAvailable() { return fs.existsSync(INTERPRETER); }
+
+/**
+ * Get the version string
+ * @returns {string}
+ */
+function getVersion() { return '2.0.0'; }
+
+module.exports = {
+    run, runString, transpileToJS, transpileToPython, check, getSpec,
+    test, isAvailable, getVersion, INTERPRETER, CLI, PIPELINE, BUILD_DIR
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "nebulara",
+  "version": "2.0.0",
+  "description": "Nebulara - AI-native universal programming language ecosystem",
+  "main": "dist/index.js",
+  "bin": {
+    "neb": "bin/neb.js",
+    "nebulara": "bin/neb.js"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "node scripts/test.js",
+    "clean": "node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "files": [
+    "bin/",
+    "dist/",
+    "build/",
+    "Compiler/",
+    "std/",
+    "test/",
+    "SPEC.md",
+    "README.md"
+  ],
+  "keywords": ["compiler", "programming-language", "ai-native", "nebulara"],
+  "author": "Codurra",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CODURRALABS/NEBULARA.git"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": ["win32", "linux", "darwin"]
+}

package/std/collections.nbs

@@ -0,0 +1,72 @@
+# Nebulara Standard Library - Collections
+# Array and collection utilities
+
+FUNC! find(arr, value):
+  LET i = 0
+  LET len = LEN(arr)
+  WHILE? i < len:
+    IF? arr[i] == value:
+      RETURN i
+    END!
+    i = i + 1
+  END!
+  RETURN -1
+END!
+
+FUNC! contains(arr, value):
+  RETURN find(arr, value) != -1
+END!
+
+FUNC! reverse_array(arr):
+  LET len = LEN(arr)
+  LET result = []
+  LET i = len - 1
+  WHILE? i >= 0:
+    result = result + [arr[i]]
+    i = i - 1
+  END!
+  RETURN result
+END!
+
+FUNC! sum_array(arr):
+  LET total = 0
+  LET i = 0
+  LET len = LEN(arr)
+  WHILE? i < len:
+    total = total + arr[i]
+    i = i + 1
+  END!
+  RETURN total
+END!
+
+FUNC! max_array(arr):
+  IF? LEN(arr) == 0:
+    RETURN 0
+  END!
+  LET m = arr[0]
+  LET i = 1
+  LET len = LEN(arr)
+  WHILE? i < len:
+    IF? arr[i] > m:
+      m = arr[i]
+    END!
+    i = i + 1
+  END!
+  RETURN m
+END!
+
+FUNC! min_array(arr):
+  IF? LEN(arr) == 0:
+    RETURN 0
+  END!
+  LET m = arr[0]
+  LET i = 1
+  LET len = LEN(arr)
+  WHILE? i < len:
+    IF? arr[i] < m:
+      m = arr[i]
+    END!
+    i = i + 1
+  END!
+  RETURN m
+END!

package/std/json.nbs

@@ -0,0 +1,15 @@
+# Nebulara Standard Library - JSON
+# Simple JSON operations (basic implementation)
+
+# JSON is not natively supported yet.
+# These are placeholder functions that demonstrate the API.
+
+FUNC! json_stringify(value):
+  RETURN TO_STRING(value)
+END!
+
+# json_parse is not yet implemented - requires FFI to C JSON parser library
+FUNC! json_parse(str):
+  PRINT "JSON.parse: not yet implemented - requires FFI to C JSON parser library"
+  RETURN NULL
+END!

package/std/kanban.nbs

@@ -0,0 +1,122 @@
+# Nebulara Standard Library - Kanban
+# Task board data structures and operations
+# Uses arrays for columns and a flat task list
+
+# Board state: four column arrays storing task IDs, and a tasks array
+LET _todo = []
+LET _in_progress = []
+LET _review = []
+LET _done = []
+LET _tasks = []
+LET _next_id = 1
+
+# Create a new task and add it to the todo column
+FUNC! create_task(title, description, priority):
+  LET task = [_next_id, title, description, priority, "todo"]
+  _tasks = _tasks + [task]
+  _todo = _todo + [_next_id]
+  _next_id = _next_id + 1
+  RETURN task[0]
+END!
+
+# Move a task to a new column
+# status must be: "todo", "in_progress", "review", or "done"
+FUNC! move_task(task_id, new_status):
+  LET i = 0
+  LET len = LEN(_tasks)
+  WHILE? i < len:
+    IF? _tasks[i][0] == task_id:
+      LET old_status = _tasks[i][4]
+      IF? old_status == new_status:
+        RETURN TRUE
+      END!
+      _tasks[i][4] = new_status
+      # Remove task_id from old column
+      IF? old_status == "todo":
+        _todo = _remove_id(_todo, task_id)
+      END!
+      IF? old_status == "in_progress":
+        _in_progress = _remove_id(_in_progress, task_id)
+      END!
+      IF? old_status == "review":
+        _review = _remove_id(_review, task_id)
+      END!
+      IF? old_status == "done":
+        _done = _remove_id(_done, task_id)
+      END!
+      # Add task_id to new column
+      IF? new_status == "todo":
+        _todo = _todo + [task_id]
+      END!
+      IF? new_status == "in_progress":
+        _in_progress = _in_progress + [task_id]
+      END!
+      IF? new_status == "review":
+        _review = _review + [task_id]
+      END!
+      IF? new_status == "done":
+        _done = _done + [task_id]
+      END!
+      RETURN TRUE
+    END!
+    i = i + 1
+  END!
+  RETURN FALSE
+END!
+
+# Get a task by ID, returns the task array or NULL
+FUNC! get_task(task_id):
+  LET i = 0
+  LET len = LEN(_tasks)
+  WHILE? i < len:
+    IF? _tasks[i][0] == task_id:
+      RETURN _tasks[i]
+    END!
+    i = i + 1
+  END!
+  RETURN NULL
+END!
+
+# Print the full board state
+FUNC! print_board():
+  PRINT "=== TODO ==="
+  _print_column(_todo)
+  PRINT "=== IN PROGRESS ==="
+  _print_column(_in_progress)
+  PRINT "=== REVIEW ==="
+  _print_column(_review)
+  PRINT "=== DONE ==="
+  _print_column(_done)
+END!
+
+# Print task summary for a list of task IDs
+FUNC! _print_column(column):
+  LET i = 0
+  LET len = LEN(column)
+  WHILE? i < len:
+    LET task = get_task(column[i])
+    IF? task != NULL:
+      PRINT task[0] + ": " + task[1] + " [" + task[3] + "]"
+    END!
+    i = i + 1
+  END!
+END!
+
+# Remove a task ID from an array of IDs, return new array
+FUNC! _remove_id(arr, task_id):
+  LET result = []
+  LET i = 0
+  LET len = LEN(arr)
+  WHILE? i < len:
+    IF? arr[i] != task_id:
+      result = result + [arr[i]]
+    END!
+    i = i + 1
+  END!
+  RETURN result
+END!
+
+# Count tasks in a column
+FUNC! column_count(column):
+  RETURN LEN(column)
+END!