@ugo-studio/jspp 0.2.5 → 0.2.6

package/README.md

@@ -3,37 +3,52 @@
 [![CI](https://github.com/ugo-studio/jspp/actions/workflows/ci.yml/badge.svg)](https://github.com/ugo-studio/jspp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**JSPP is a modern, experimental transpiler that converts JavaScript code into high-performance, standard C++23.**
+**JSPP is a modern, experimental transpiler that converts JavaScript and TypeScript code into high-performance, standard C++23.**
 
 The primary goal of this project is to achieve a near-perfect translation of JavaScript's dynamic nature and core features into the statically-typed, compiled world of C++, exploring modern C++ capabilities to bridge the gap between these two powerful languages.
 
 ## About The Project
 
-JavaScript is flexible and dynamic; C++ is performant and type-safe. JSPP aims to offer the best of both worlds. By transpiling JS to C++, we can potentially run JavaScript logic in environments where C++ is native, with significant performance gains and opportunities for low-level interoperability.
+JavaScript is flexible and dynamic; C++ is performant and type-safe. JSPP aims to offer the best of both worlds. By transpiling JS/TS to C++, we can potentially run JavaScript logic in environments where C++ is native, with significant performance gains and opportunities for low-level interoperability.
 
-This project serves as a deep dive into compiler design, language semantics, and the expressive power of modern C++. The current implementation translates an entire JavaScript file into a single C++ `main` function, cleverly using `std::shared_ptr<std::any>` to replicate JavaScript's dynamic typing, garbage-collection-like memory management, and complex features like closures.
+This project serves as a deep dive into compiler design, language semantics, and the expressive power of modern C++. The current implementation translates an entire JavaScript/TypeScript file into a single C++ `main` function, cleverly using `std::shared_ptr<std::any>` (and custom wrappers) to replicate JavaScript's dynamic typing, garbage-collection-like memory management, and complex features like closures.
 
 ## Features
 
-JSPP currently supports a foundational set of JavaScript features:
+JSPP currently supports a comprehensive set of JavaScript features:
 
-- **Dynamic Variables:** Declaration (`let`, `const` and `var`), assignment, and type changes at runtime.
-- **Primitive Types:** `undefined`, `null`, `boolean`, `number`, `string`, `object` and `array`.
+- **Languages:** JavaScript (`.js`) and TypeScript (`.ts`) support.
+- **Dynamic Variables:** Declaration (`let`, `const`, `var`), assignment, and type changes at runtime.
+- **Primitive Types:** `undefined`, `null`, `boolean`, `number`, `string`, `symbol`.
 - **Functions:**
-  - Function declarations and arrow functions.
-  - Correct hoisting for both variables and functions.
-  - Closures with proper lexical scoping and lifetime management.
-- **Operators:** All arithmetic (`+`, `-`, `*`) and assignment (`=`) operators.
-- **Control Flow:** `void` operator.
-- **Built-in APIs:** A `console` object with `log()`, `warn()`, `error()`, and `time()` methods.
+  - Function declarations, arrow functions, and function expressions.
+  - **Generators:** `function*` and `yield` support.
+  - **Async/Await:** `async function` and `await` support (built on C++20 coroutines).
+  - Closures with proper lexical scoping.
+- **Object Oriented:**
+  - **Classes:** Class declarations, constructors, methods, getters/setters, and inheritance (`extends`).
+  - **Prototypes:** Prototype chain traversal and manipulation.
+- **Control Flow:**
+  - `if`, `else if`, `else`.
+  - Loops: `for`, `for-of`, `for-in`, `while`, `do-while`.
+  - `switch` statements.
+  - `try`, `catch`, `finally` blocks.
+- **Operators:** Full suite of arithmetic, assignment, comparison, logical, bitwise, and unary operators (including `typeof`, `delete`, `void`, `instanceof`, `in`).
+- **Standard Library:**
+  - **Console:** `log`, `warn`, `error`, `time`, `timeEnd`.
+  - **Math:** Comprehensive `Math` object implementation.
+  - **Timers:** `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`.
+  - **Promise:** Full `Promise` implementation with chaining.
+  - **Error:** Standard `Error` class and stack traces.
+  - **Arrays & Objects:** Extensive methods support (`map`, `filter`, `reduce`, `push`, `pop`, `Object.keys`, etc.).
 
 ## Reserved Keywords
 
 JSPP reserves certain keywords to avoid conflicts with the generated C++ code and internal mechanisms. The following keywords are reserved and cannot be used as variable names:
 
-- `std`: Reserved to prevent conflicts with the C++ standard library namespace.
-- `jspp`: Reserved for internal use by the JSPP transpiler.
-- `co_yield`,`co_return`,`co_await`: Reserved to prevent conflicts with the c++ couroutine keywords.
+- `jspp`: Reserved for internal use by the transpiler.
+- `std`: Reserved to prevent conflicts with the C++ standard library.
+- `co_yield`, `co_return`, `co_await`: Reserved for C++ coroutine mechanics.
 
 Using these keywords as variable names will result in a `SyntaxError`.
 
@@ -51,8 +66,7 @@ To contribute to JSPP or run its test suite, follow these steps:
 
 ### Prerequisites
 
-- **Node.js:** This project uses Node.js for package management and script execution.
-  - [Install Node.js >= v20.0.0](https://nodejs.org/)
+- **Bun:** This project uses [Bun](https://bun.sh/) for package management, script execution, and testing.
 - **C++ Compiler:** A compiler with support for C++23 is required. This project is tested with `g++`.
   - `g++` (MinGW on Windows, or available via build-essentials on Linux)
 
@@ -64,31 +78,31 @@ To contribute to JSPP or run its test suite, follow these steps:
     ```
 2.  Install dependencies:
     ```sh
-    npm install
+    bun install
     ```
 
 ## Usage
 
-The primary way to use JSPP is via its command-line interface. This will transpile your `.js` file to C++, compile it, and execute the resulting binary.
+The primary way to use JSPP is via its command-line interface. This will transpile your file to C++, compile it, and execute the resulting binary.
 
 ```sh
-jspp <path-to-your-js-file>
+jspp <path-to-your-file>
 ```
 
 **Example:**
 
-To run a sample JavaScript file located at `my-code/hello.js`:
+To run a sample TypeScript file located at `my-code/test.ts`:
 
 ```sh
-jspp my-code/hello.js
+jspp my-code/test.ts
 ```
 
-The transpiled C++ file and executable will be generated in the same directory as the input file and cleaned up after execution.
+The transpiled C++ file and executable will be generated in the same directory as the input file and cleaned up after execution (unless `--keep-cpp` is used).
 
-You can also run the test suite, which will transpile all the JavaScript test cases in `test/cases/`, build the resulting C++ files, and run them.
+You can also run the test suite:
 
 ```sh
-npm test
+bun test
 ```
 
 ## Roadmap
@@ -101,38 +115,39 @@ This project is ambitious, and there is a long and exciting road ahead. Here is
 
 This phase focuses on building a solid foundation that correctly models JavaScript's core runtime behavior.
 
-- [x] Dynamic Variables & Primitives (`let`, `const`, `var`, `undefined`, `null`, `string`, `number`, `boolean`, etc.)
+- [x] Dynamic Variables & Primitives
 - [x] Function Declarations & Arrow Functions
 - [x] Correct Hoisting for Variables and Functions
 - [x] Closures & Lexical Scoping
-- [x] `if-elseif-else` conditions
+- [x] Basic Control Flow (`if`, `loops`)
 - [x] Basic `console` API
 
 ---
 
 ### **Phase 2: Expanded Language Support**
 
-This phase will broaden the range of supported JavaScript syntax and features.
+This phase broadens the range of supported JavaScript syntax and features.
 
 - [x] **Error Handling**: `try`/`catch`/`finally` blocks and `throw`.
-- [x] **Objects:** Literals, property access (dot and bracket notation), methods.
-- [x] **Arrays:** Literals, indexing, and core methods (`.push`, `.pop`, `.length`, etc.).
+- [x] **Objects & Classes:** Classes, inheritance, literals, property access.
+- [x] **Arrays:** Literals, indexing, and core methods.
 - [x] **Operators:** Full suite of arithmetic, logical, and comparison operators.
-- [x] **Control Flow:** tenary operators, `for` loops, `while` loops, `switch`.
+- [x] **Advanced Control Flow:** `switch`, `for-of`, `for-in`, generators.
+- [x] **TypeScript Support:** Compilation of `.ts` files.
 
-### **Phase 3: Interoperability & Standard Library**
+### Phase 3: Interoperability & Standard Library
 
-This phase will focus on building out the standard library and enabling modular code.
+This phase focuses on building out the standard library and enabling modular code.
 
-- [ ] **JS Standard Library:** Implementation of common built-in objects and functions (`Math`, `Date`, `String.prototype.*`, `Array.prototype.*`).
-- [x] **Asynchronous Operations:** A C++ implementation of the JavaScript event loop, `Promise`, and `async/await`.
+- [ ] **JS Standard Library:** Implementation of common built-in objects. (Currently supports: `Math`, `Symbol`, `Error`, `String`, `Array`, `Object`, `Timer`). **Pending:** `Date`, `Temporal`, `Map`, `Set`, `JSON`, etc.
+- [x] **Asynchronous Operations:** Event loop, `Promise`, `async/await`, and timers (`setTimeout`).
 - [ ] **Module System:** Support for `import` and `export` to transpile multi-file projects.
 
 ### **Phase 4: Optimization & Advanced Features**
 
 With a feature-complete transpiler, the focus will shift to performance and advanced capabilities.
 
-- [ ] **Performance Benchmarking:** Create a suite to compare transpiled C++ performance against V8 and other JS engines.
+- [ ] **Performance Benchmarking:** Create a suite to compare transpiled C++ performance against V8.
 - [ ] **C++ Interoperability:** Define a clear API for calling C++ functions from the transpiled JavaScript and vice-versa.
 
 ## Contributing

package/dist/analysis/scope.js

@@ -1,4 +1,5 @@
 import * as ts from "typescript";
+import { CompilerError } from "../core/error.js";
 export const RESERVED_KEYWORDS = new Set([
     "jspp",
     "std",
@@ -86,6 +87,9 @@ export class ScopeManager {
     define(name, type) {
         // if (name === "named" || name === "letVal") console.log("Defining", name, "in scope. isBuiltin:", type.isBuiltin, " type:", type.type);
         if (this.reservedKeywords.has(name) && !type.isBuiltin) {
+            if (type.declaration) {
+                throw new CompilerError(`Unexpected reserved word "${name}"`, type.declaration, "SyntaxError");
+            }
             throw new Error(`SyntaxError: Unexpected reserved word "${name}"`);
         }
         this.currentScope.define(name, type);
@@ -93,6 +97,9 @@ export class ScopeManager {
     // Defines a `var` variable (hoisted to function or global scope).
     defineVar(name, type) {
         if (this.reservedKeywords.has(name) && !type.isBuiltin) {
+            if (type.declaration) {
+                throw new CompilerError(`Unexpected reserved word "${name}"`, type.declaration, "SyntaxError");
+            }
             throw new Error(`SyntaxError: Unexpected reserved word "${name}"`);
         }
         let scope = this.currentScope;

package/dist/analysis/typeAnalyzer.js

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
-import { isBuiltinObject } from "../core/codegen/helpers.js";
+import { isBuiltinObject, shouldIgnoreStatement, } from "../core/codegen/helpers.js";
+import { CompilerError } from "../core/error.js";
 import { Traverser } from "../core/traverser.js";
 import { Scope, ScopeManager } from "./scope.js";
 export class TypeAnalyzer {
@@ -167,12 +168,12 @@ export class TypeAnalyzer {
                     const breakNode = node;
                     if (breakNode.label) {
                         if (!this.labelStack.includes(breakNode.label.text)) {
-                            throw new Error(`SyntaxError: Undefined label '${breakNode.label.text}'`);
+                            throw new CompilerError(`Undefined label '${breakNode.label.text}'`, breakNode.label, "SyntaxError");
                         }
                     }
                     else {
                         if (this.loopDepth === 0 && this.switchDepth === 0) {
-                            throw new Error("SyntaxError: Unlabeled break must be inside an iteration or switch statement");
+                            throw new CompilerError("Unlabeled break must be inside an iteration or switch statement", node, "SyntaxError");
                         }
                     }
                 },
@@ -182,14 +183,14 @@ export class TypeAnalyzer {
                     const continueNode = node;
                     if (continueNode.label) {
                         if (!this.labelStack.includes(continueNode.label.text)) {
-                            throw new Error(`SyntaxError: Undefined label '${continueNode.label.text}'`);
+                            throw new CompilerError(`Undefined label '${continueNode.label.text}'`, continueNode.label, "SyntaxError");
                         }
                         // Also need to check if the label belongs to a loop, but that's harder here.
                         // The TS checker should handle this. We'll assume for now it does.
                     }
                     else {
                         if (this.loopDepth === 0) {
-                            throw new Error("SyntaxError: Unlabeled continue must be inside an iteration statement");
+                            throw new CompilerError("Unlabeled continue must be inside an iteration statement", node, "SyntaxError");
                         }
                     }
                 },
@@ -208,10 +209,7 @@ export class TypeAnalyzer {
                         // Catch invalid parameters
                         node.parameters.forEach((p) => {
                             if (p.getText() == "this") {
-                                const sourceFile = node.getSourceFile();
-                                const { line, character } = sourceFile
-                                    .getLineAndCharacterOfPosition(p.getStart());
-                                throw new SyntaxError(`Cannot use 'this' as a parameter name.\n\n${" ".repeat(6)}at ${sourceFile.fileName}:${line + 1}:${character + 1}\n`);
+                                throw new CompilerError("Cannot use 'this' as a parameter name.", p, "SyntaxError");
                             }
                         });
                         // Define parameters in the new scope
@@ -250,10 +248,7 @@ export class TypeAnalyzer {
                         // Catch invalid parameters
                         node.parameters.forEach((p) => {
                             if (p.getText() == "this") {
-                                const sourceFile = node.getSourceFile();
-                                const { line, character } = sourceFile
-                                    .getLineAndCharacterOfPosition(p.getStart());
-                                throw new SyntaxError(`Cannot use 'this' as a parameter name.\n\n${" ".repeat(6)}at ${sourceFile.fileName}:${line + 1}:${character + 1}\n`);
+                                throw new CompilerError("Cannot use 'this' as a parameter name.", p, "SyntaxError");
                             }
                         });
                         // Define parameters in the new scope
@@ -288,17 +283,14 @@ export class TypeAnalyzer {
                             this.scopeManager.define(funcName, funcType);
                             this.functionTypeInfo.set(node, funcType);
                         }
+                        this.scopeManager.enterScope(node);
+                        this.nodeToScope.set(node, this.scopeManager.currentScope);
                         // Catch invalid parameters
                         node.parameters.forEach((p) => {
                             if (p.getText() == "this") {
-                                const sourceFile = node.getSourceFile();
-                                const { line, character } = sourceFile
-                                    .getLineAndCharacterOfPosition(p.getStart());
-                                throw new SyntaxError(`Cannot use 'this' as a parameter name.\n\n${" ".repeat(6)}at ${sourceFile.fileName}:${line + 1}:${character + 1}\n`);
+                                throw new CompilerError("Cannot use 'this' as a parameter name.", p, "SyntaxError");
                             }
                         });
-                        this.scopeManager.enterScope(node);
-                        this.nodeToScope.set(node, this.scopeManager.currentScope);
                         // Define parameters in the new scope
                         node.parameters.forEach((p) => this.scopeManager.define(p.name.getText(), {
                             type: "auto",
@@ -336,6 +328,25 @@ export class TypeAnalyzer {
                     this.scopeManager.exitScope();
                 },
             },
+            EnumDeclaration: {
+                enter: (node) => {
+                    const enumNode = node;
+                    if (enumNode.name) {
+                        const name = enumNode.name.getText();
+                        const typeInfo = {
+                            type: "object", // Enums are objects
+                            declaration: enumNode,
+                            needsHeapAllocation: true,
+                        };
+                        this.scopeManager.define(name, typeInfo);
+                    }
+                    // Enums don't create a new scope for variables, but they are objects.
+                    // We don't strictly need to enterScope unless we want to track something inside.
+                    // But standard JS/TS behavior doesn't really have block scope inside enum definition that leaks out or captures differently.
+                    // However, we map nodes to scopes.
+                    this.nodeToScope.set(node, this.scopeManager.currentScope);
+                },
+            },
             MethodDeclaration: {
                 enter: (node) => {
                     if (ts.isMethodDeclaration(node)) {
@@ -397,6 +408,16 @@ export class TypeAnalyzer {
             VariableDeclaration: {
                 enter: (node) => {
                     if (ts.isVariableDeclaration(node)) {
+                        // Check if it is an ambient declaration (declare var/let/const ...)
+                        let isAmbient = false;
+                        if (ts.isVariableDeclarationList(node.parent) &&
+                            ts.isVariableStatement(node.parent.parent)) {
+                            if (shouldIgnoreStatement(node.parent.parent)) {
+                                isAmbient = true;
+                            }
+                        }
+                        if (isAmbient)
+                            return;
                         const name = node.name.getText();
                         const isBlockScoped = (node.parent.flags &
                             (ts.NodeFlags.Let | ts.NodeFlags.Const)) !== 0;

package/dist/ast/symbols.js

@@ -5,14 +5,15 @@ export var DeclarationType;
     DeclarationType["const"] = "const";
     DeclarationType["function"] = "function";
     DeclarationType["class"] = "class";
+    DeclarationType["enum"] = "enum";
 })(DeclarationType || (DeclarationType = {}));
 export class DeclaredSymbol {
     type;
-    checked;
+    checks;
     func;
     constructor(type) {
         this.type = type;
-        this.checked = {
+        this.checks = {
             initialized: false,
         };
         this.func = null;
@@ -22,8 +23,8 @@ export class DeclaredSymbol {
             this.type === DeclarationType.var;
     }
     updateChecked(update) {
-        this.checked = {
-            ...this.checked,
+        this.checks = {
+            ...this.checks,
             ...update,
         };
     }
@@ -53,8 +54,8 @@ export class DeclaredSymbols {
     }
     add(name, value) {
         const sym = new DeclaredSymbol(value.type);
-        if (value.checked !== undefined)
-            sym.updateChecked(value.checked);
+        if (value.checks !== undefined)
+            sym.updateChecked(value.checks);
         if (value.func !== undefined)
             sym.updateFunc(value.func);
         return this.symbols.set(name, sym);
@@ -64,8 +65,8 @@ export class DeclaredSymbols {
         if (sym) {
             if (update.type !== undefined)
                 sym.type = update.type;
-            if (update.checked !== undefined)
-                sym.updateChecked(update.checked);
+            if (update.checks !== undefined)
+                sym.updateChecked(update.checks);
             if (update.func !== undefined)
                 sym.updateFunc(update.func);
             return this.symbols.set(name, sym);

package/dist/cli/args.js

@@ -0,0 +1,59 @@
+import path from "path";
+import pkg from "../../package.json" with { type: "json" };
+import { COLORS } from "./colors.js";
+export function parseArgs(rawArgs) {
+    let jsFilePathArg = null;
+    let isRelease = false;
+    let keepCpp = false;
+    let outputExePath = null;
+    let scriptArgs = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (!arg)
+            continue;
+        if (arg === "--") {
+            scriptArgs = rawArgs.slice(i + 1);
+            break;
+        }
+        if (arg === "--release") {
+            isRelease = true;
+        }
+        else if (arg === "--keep-cpp") {
+            keepCpp = true;
+        }
+        else if (arg === "-o" || arg === "--output") {
+            if (i + 1 < rawArgs.length) {
+                outputExePath = rawArgs[i + 1] ?? null;
+                i++;
+            }
+            else {
+                console.error(`${COLORS.red}Error: --output requires a file path argument.${COLORS.reset}`);
+                process.exit(1);
+            }
+        }
+        else if (arg.startsWith("-")) {
+            console.warn(`${COLORS.yellow}Warning: Unknown argument '${arg}'${COLORS.reset}`);
+        }
+        else {
+            if (jsFilePathArg) {
+                console.error(`${COLORS.red}Error: Multiple input files specified.${COLORS.reset}`);
+                process.exit(1);
+            }
+            jsFilePathArg = arg;
+        }
+    }
+    if (!jsFilePathArg) {
+        console.log(`${COLORS.bold}JSPP Compiler${COLORS.reset} ${COLORS.dim}v${pkg.version}${COLORS.reset}`);
+        console.log(`${COLORS.bold}Usage:${COLORS.reset} jspp <path-to-js-file> [--release] [--keep-cpp] [-o <output-path>] [-- <args...>]`);
+        process.exit(1);
+    }
+    return {
+        jsFilePath: path.resolve(process.cwd(), jsFilePathArg),
+        isRelease,
+        keepCpp,
+        outputExePath: outputExePath
+            ? path.resolve(process.cwd(), outputExePath)
+            : null,
+        scriptArgs,
+    };
+}

package/dist/cli/colors.js

@@ -0,0 +1,9 @@
+export const COLORS = {
+    reset: "\x1b[0m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+};

package/dist/cli/file-utils.js

@@ -0,0 +1,20 @@
+import fs from "fs/promises";
+import path from "path";
+export async function getLatestMtime(dirPath) {
+    let maxMtime = 0;
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            const nestedMtime = await getLatestMtime(fullPath);
+            if (nestedMtime > maxMtime)
+                maxMtime = nestedMtime;
+        }
+        else {
+            const stats = await fs.stat(fullPath);
+            if (stats.mtimeMs > maxMtime)
+                maxMtime = stats.mtimeMs;
+        }
+    }
+    return maxMtime;
+}

package/dist/cli/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { spawn } from "child_process";
+import fs from "fs/promises";
+import path from "path";
+import pkg from "../../package.json" with { type: "json" };
+import { Interpreter } from "../index.js";
+import { CompilerError } from "../core/error.js";
+import { parseArgs } from "./args.js";
+import { COLORS } from "./colors.js";
+import { getLatestMtime } from "./file-utils.js";
+import { Spinner } from "./spinner.js";
+const pkgDir = path.dirname(path.dirname(import.meta.dirname));
+async function main() {
+    const { jsFilePath, isRelease, keepCpp, outputExePath, scriptArgs } = parseArgs(process.argv.slice(2));
+    const ext = path.extname(jsFilePath);
+    const jsFileName = path.basename(jsFilePath, ext);
+    const sourceDir = path.dirname(jsFilePath);
+    // Intermediate C++ file goes alongside the source JS file
+    const cppFilePath = path.join(sourceDir, `${jsFileName}.cpp`);
+    // Determine output executable path
+    let exeFilePath;
+    if (outputExePath) {
+        exeFilePath = outputExePath;
+    }
+    else {
+        const ext = process.platform === "win32" ? ".exe" : "";
+        exeFilePath = path.join(sourceDir, `${jsFileName}${ext}`);
+    }
+    // Mode Configuration
+    const mode = isRelease ? "release" : "debug";
+    console.log(`${COLORS.bold}JSPP Compiler${COLORS.reset} ${COLORS.dim}v${pkg.version}${COLORS.reset}`);
+    console.log(`Mode: ${isRelease ? COLORS.green : COLORS.yellow}${mode.toUpperCase()}${COLORS.reset}\n`);
+    const flags = isRelease ? ["-O3", "-DNDEBUG"] : ["-O0"];
+    if (process.platform === "win32") {
+        flags.push("-Wa,-mbig-obj");
+    }
+    const pchDir = path.resolve(pkgDir, "prelude-build", mode);
+    const spinner = new Spinner("Initializing...");
+    try {
+        spinner.start();
+        // 1. Interpreter Phase
+        spinner.update(`Reading ${path.basename(jsFilePath)}...`);
+        const jsCode = await fs.readFile(jsFilePath, "utf-8");
+        spinner.update("Transpiling to C++...");
+        const interpreter = new Interpreter();
+        const { cppCode, preludePath } = interpreter.interpret(jsCode, jsFilePath);
+        // Ensure directory for cpp file exists (should exist as it's source dir, but for safety if we change logic)
+        await fs.mkdir(path.dirname(cppFilePath), { recursive: true });
+        await fs.writeFile(cppFilePath, cppCode);
+        spinner.succeed(`Generated cpp`);
+        // 2. Precompiled Header Check
+        spinner.text = "Checking precompiled headers...";
+        spinner.start();
+        const pchFile = path.join(pchDir, "index.hpp.gch");
+        let shouldRebuild = false;
+        try {
+            const pchStats = await fs.stat(pchFile);
+            const sourceMtime = await getLatestMtime(preludePath);
+            if (sourceMtime > pchStats.mtimeMs) {
+                shouldRebuild = true;
+            }
+        }
+        catch (e) {
+            shouldRebuild = true;
+        }
+        if (shouldRebuild) {
+            spinner.update("Rebuilding precompiled headers (this may take a while)...");
+            // Use spawn (async) instead of spawnSync to keep spinner alive
+            const rebuild = spawn("bun", [
+                "run",
+                "scripts/precompile-headers.ts",
+            ], {
+                cwd: pkgDir,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const stderrChunks = [];
+            if (rebuild.stderr) {
+                rebuild.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+            }
+            const exitCode = await new Promise((resolve) => {
+                rebuild.on("close", (code) => resolve(code ?? 1));
+            });
+            if (exitCode !== 0) {
+                const stderr = Buffer.concat(stderrChunks).toString();
+                spinner.fail("Failed to rebuild precompiled headers");
+                console.error(stderr);
+                process.exit(1);
+            }
+            spinner.succeed("Precompiled headers updated");
+        }
+        else {
+            spinner.succeed("Precompiled headers");
+        }
+        // 3. Compilation Phase
+        spinner.text = `Compiling binary...`;
+        spinner.start();
+        // Ensure output directory exists
+        await fs.mkdir(path.dirname(exeFilePath), { recursive: true });
+        const compile = spawn("g++", [
+            "-std=c++23",
+            ...flags,
+            cppFilePath,
+            "-o",
+            exeFilePath,
+            "-I",
+            pchDir,
+            "-I",
+            preludePath,
+        ], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const compileStderrChunks = [];
+        if (compile.stderr) {
+            compile.stderr.on("data", (chunk) => compileStderrChunks.push(chunk));
+        }
+        const compileExitCode = await new Promise((resolve) => {
+            compile.on("close", (code) => resolve(code ?? 1));
+        });
+        if (compileExitCode !== 0) {
+            const stderr = Buffer.concat(compileStderrChunks).toString();
+            spinner.fail(`Compilation failed`);
+            console.error(stderr);
+            process.exit(1);
+        }
+        spinner.succeed(`Compiled to ${COLORS.green}${COLORS.bold}${path.basename(exeFilePath)}${COLORS.reset}`);
+        // Clean up C++ file if not requested to keep
+        if (!keepCpp) {
+            try {
+                await fs.unlink(cppFilePath);
+            }
+            catch (e) {
+                // Ignore error if file cannot be deleted
+            }
+        }
+        // 4. Execution Phase
+        console.log(`\n${COLORS.cyan}--- Running Output ---${COLORS.reset}`);
+        const run = spawn(exeFilePath, scriptArgs, {
+            stdio: "inherit",
+        });
+        const runExitCode = await new Promise((resolve) => {
+            run.on("close", (code) => resolve(code ?? 1));
+        });
+        console.log(`${COLORS.cyan}----------------------${COLORS.reset}\n`);
+        if (runExitCode !== 0) {
+            console.error(`${COLORS.red}Execution failed with exit code ${runExitCode}${COLORS.reset}`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if (error instanceof CompilerError) {
+            spinner.fail("Compilation failed");
+            console.error(error.getFormattedError());
+            process.exit(1);
+        }
+        spinner.fail("An unexpected error occurred");
+        console.error(error);
+        process.exit(1);
+    }
+}
+main();