@ezetgalaxy/titan 25.11.4 → 25.11.6

package/README.md

@@ -1,44 +1,65 @@
-
 ***
 
-## TITAN 🚀
+## TITAN PLANET 🚀  
 JavaScript Simplicity. Rust Power.
 
-Titan is a JavaScript-first backend framework that compiles your JS routes and actions into a production-grade Rust + Axum server.
+Titan is a JavaScript-first backend framework that compiles your JS routes and actions into a production-grade **Rust + Axum native server**.
+
+Developers write **zero Rust**, yet deploy a high-performance, safe, fully native backend with excellent DX (developer experience).
+
+Titan = Next.js DX × Rust performance × JavaScript simplicity
 
-Developers write zero Rust, yet deploy a native Rust backend with extreme performance, safety, and scalability.
+---
 
-Titan turns your JavaScript backend into:
+## ⚙ Requirements
 
-- A Rust Axum HTTP server  
-- A JS action execution runtime (via Boa)  
-- A standalone binary ready for Railway, Fly.io, VPS, Docker  
-- A fully portable server with no Node.js required in production  
+Before using Titan, ensure your system has:
 
-Titan = Next.js DX × Rust performance × JS developer simplicity
+### **1. Rust (latest stable)**
+Install from:
+https://rust-lang.org/tools/install/
 
-### Features
+### **2. Node.js (v18+)**
+Required for:
+- Titan CLI  
+- esbuild  
+- JS → Rust compilation process  
 
-- Write backend logic in JavaScript  
-- Compile into native Rust backend  
-- Titan DSL (t.post(), t.start())  
-- Automatic route generation  
-- Automatic JS action bundling  
-- Rust Axum server runtime  
-- JavaScript execution via Boa (sandboxed)  
-- Hot-reload dev server   // development in progress
-- Production binary output  
+Check version:
+```bash
+node -v
+npm -v
+rustc -V
+```
+
+---
+
+## ✨ Features
+
+- Write your backend in **pure JavaScript**
+- Compile into a **native Rust HTTP server**
+- Titan DSL: `t.get()`, `t.post()`, `t.start()`
+- Automatic **route generation**
+- Automatic **JS action bundling**
+- Fast **Rust Axum runtime**
+- JavaScript execution via **Boa engine**
+- **Hot Reload Dev Server** (edit → rebuild → restart automatically)
+- Production output: **single binary**
 - Zero-config deployment
 
-### Installation
+---
+
+## 📦 Installation
 
 Install the Titan CLI globally:
 
 ```bash
-npm install -g titan-cli
+npm install -g @ezetgalaxy/titan
 ```
 
-### Create a New Titan Project
+---
+
+## 🚀 Create a New Titan Project
 
 ```bash
 tit init my-app
@@ -46,191 +67,219 @@ cd my-app
 tit dev
 ```
 
-This will:
+Titan will automatically:
+
+- Create project structure  
+- Generate routes from `/app/app.js`  
+- Bundle JS actions into `.jsbundle` files  
+- Start the **Rust Axum dev server with Hot Reload**  
 
-- Generate Titan project structure  
-- Build routes from /app/app.js  
-- Bundle JS actions into [.jsbundle] files  
-- Start the Rust Axum development server with hot reload
+---
 
-### Project Structure
+# 📁 Project Structure
 
 ```
 my-app/
 ├── app/
-│   ├── app.js
-│   └── actions/
-│       └── hello.js
+│   ├── app.js                 # Titan routes (DSL)
+│   └── actions/
+│       └── hello.js           # Titan action
 │
 ├── titan/
-│   |── titan.js
-|   |__ bundle.js
-│
-├── cli/
-│   └── bundle.js
+│   ├── titan.js               # Titan DSL
+│   ├── bundle.js              # Bundler (esbuild)
+│   └── dev.js                 # Hot reload engine
 │
-├── server/            ← Rust backend ([translate:auto generated])
-│   ├── src/
-│   ├── actions/
-│   ├── titan/
-│   ├── target/
-│   ├── routes.json
-│   ├── action_map.json
-│   └── titan-server   ← final binary
+├── server/                    # Rust backend (auto generated)
+│   ├── src/
+│   ├── actions/               # JS → .jsbundle compiled actions
+│   ├── titan/                 # internal runtime files
+│   ├── target/                # Cargo build output
+│   ├── routes.json
+│   ├── action_map.json
+│   └── titan-server           # Final Rust binary
 │
 └── package.json
 ```
 
-### Example: Titan Action
+This is the complete Titan architecture:  
+**JS input → Rust server output → Native production binary.**
+
+---
+
+# 🧩 Example: Titan Action
 
 **app/actions/hello.js**
 
 ```js
 function hello(req) {
-  return { message: "Hello from Titan!" };
+  return { message: "Hello from Titan!" };
 }
 
-globalThis.hello = hello
+globalThis.hello = hello;
 ```
 
-This registers a global function _hello_ for the Rust runtime.
+---
 
-### Example: Titan Routes
+# 🛣 Example: Titan Routes (DSL)
 
 **app/app.js**
 
 ```js
 import t from "../titan/titan.js";
 
-
 // POST /hello → hello action
 t.post("/hello").action("hello");
 
 // GET / → reply text
 t.get("/").reply("Welcome to Titan");
 
-t.start(3000, "Titan is running!");
+t.start(3000, "Ready to land on Titan Planet 🚀");
 ```
 
-Titan generates routing metadata:
+Titan generates:
+
+- `server/routes.json`
+- `server/action_map.json`
 
-- server/routes.json  
-- server/action_map.json  
+Used by the Rust runtime to dispatch requests.
 
-These are then used by the Rust server.
+---
 
-### Development Mode
+# 🔥 Hot Reload Dev Mode
+
+Start development mode:
 
 ```bash
 tit dev
 ```
 
-Titan will:
+Titan Dev Mode will:
+
+- Regenerate routes on every save  
+- Rebundle actions automatically  
+- **Kill and restart the Rust server safely**  
+- Give full hot reload like modern JS frameworks  
+
+Full DX flow:
+
+```
+Save file → auto rebuild → auto restart → updated API
+```
+
+Supports:
 
-- Generate route definitions  
-- Bundle JS into .jsbundle files  
-- Start Axum Rust server with live reload
+- Editing `app/app.js`
+- Editing `app/actions/*.js`
+- Fast rebuilds via esbuild
 
-### Production Build
+---
+
+# 🏭 Production Build
 
 ```bash
 tit build
 ```
 
-This produces the final deployment-ready output:
+Production output goes into:
 
 ```
 server/
-  titan-server          ← release binary
-  routes.json
-  action_map.json
-  actions/*.jsbundle
-  titan/titan.jsbundle
+  titan-server
+  routes.json
+  action_map.json
+  actions/*.jsbundle
 ```
 
-Everything required for production is inside the server/ folder.
-
-### Deploying Titan
+You deploy **only the server folder**.
 
-You deploy only the /server folder.
+---
 
-Example (Railway):
+# ☁ Deploying Titan
 
-Build locally:
-
-```bash
-tit build
-```
+After `tit build`, deploy the `server/` folder anywhere:
 
-Upload the /server folder
+- Railway  
+- Fly.io  
+- Docker  
+- VPS  
+- Render  
+- Bare metal  
 
-Set start command:
+Start command:
 
 ```bash
 ./titan-server
 ```
 
-No Node.js needed in production. Titan servers run as pure Rust native binaries.
-
-### How Titan Works Internally
+No Node.js needed in production — Titan runs as a pure Rust binary.
 
-1. JavaScript DSL
+---
 
-You write server logic using the Titan DSL:
+# 🧠 How Titan Works (Internals)
 
-- t.get()  
-- t.post()  
-- t.start()
+### 1. JavaScript DSL  
+You write backend logic using Titan’s intuitive DSL.
 
-2. Bundler
+### 2. Bundler  
+Titan uses esbuild to compile JS actions into `.jsbundle`.
 
-Titan bundles actions using esbuild into .jsbundle.
+### 3. Metadata  
+`t.start()` writes:
 
+- `routes.json`
+- `action_map.json`
 
-4. Rust Server
+### 4. Rust Server  
+Axum server:
 
-The Rust Axum server:
-
-- Loads .jsbundle files  
+- Loads `.jsbundle` actions  
 - Injects request data  
-- Executes JS functions via Boa  
-- Returns Rust → JSON → client
-
-5. Production Output
+- Executes JS via Boa  
+- Returns JSON response to user  
 
-Titan outputs:
+### 5. Production Output  
+Titan produces:
 
-- Native Rust binary  
+- A **native binary**  
 - JS bundles  
-- Route maps
+- Route maps  
+- Entire backend in one folder  
 
-### Why Titan Exists
+---
 
-Titan targets JS developers who want:
+# 🎯 Why Titan Exists
 
-- Rust backend performance  
-- Without needing Rust knowledge  
-- With full JS developer experience  
-- And deployment as easy as Node
+Titan exists for developers who want:
+
+- Rust performance  
+- JavaScript simplicity  
+- Zero Rust learning curve  
+- Zero config deployment  
+- Modern DX + native speed  
 
 Titan bridges two worlds:
 
-JavaScript flexibility + Rust performance
+**JavaScript Productivity × Rust Performance**
+
+---
 
-### Version
+# 📌 Version
 
-Titan v1 (Current)
+**Titan v1 — Stable**
 
 - JS → Rust server compiler  
-- JavaScript Action Engine  
-- Axum runtime  
+- Action Engine  
+- Axum Runtime  
 - Titan DSL  
-- Hot reload  
-- Railway deployment
+- Hot Reload Dev Mode  
+- Railway/Fly.io Deployment  
 
+---
 
-### Contributing
+# 🤝 Contributing
 
-PRs, issues, and discussions are welcome.
+PRs, issues, suggestions, and feature discussions are welcome.
+
+***
 
-***

package/index.js

@@ -1,9 +1,10 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import fs from "fs";
 import path from "path";
 import { execSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
 
+// __dirname in ES modules
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -17,9 +18,7 @@ const bold = (t) => `\x1b[1m${t}\x1b[0m`;
 const args = process.argv.slice(2);
 const cmd = args[0];
 
-// ------------------------------------------
 // COPY TEMPLATES
-// ------------------------------------------
 function copyDir(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
 
@@ -35,23 +34,19 @@ function copyDir(src, dest) {
     }
 }
 
-// ------------------------------------------
 // HELP
-// ------------------------------------------
 function help() {
     console.log(`
 ${bold(cyan("Titan CLI"))}
 
 ${green("tit init <project>")}   Create new Titan project
-${green("tit dev")}              Run dev server (routes + bundle + cargo)
-${green("tit build")}            Build Rust release
+${green("tit dev")}              Dev mode (hot reload)
+${green("tit build")}            Build production Rust server
 ${green("tit start")}            Start production binary
 `);
 }
 
-// ------------------------------------------
 // INIT PROJECT
-// ------------------------------------------
 function initProject(name) {
     if (!name) return console.log(red("Usage: tit init <project>"));
 
@@ -68,21 +63,14 @@ function initProject(name) {
     copyDir(templateDir, target);
 
     console.log(green("✔ Titan project created!"));
-    console.log(cyan("Installing Titan dependencies..."));
+    console.log(cyan("Installing dependencies..."));
 
-    const deps = [
-        "esbuild",
-    ];
-
-    execSync(`npm install ${deps.join(" ")} --silent`, {
+    execSync(`npm install esbuild --silent`, {
         cwd: target,
         stdio: "inherit"
     });
 
-    console.log(green("✔ Dependencies installed successfully"));
-
-
-    console.log(green("✔ Titan project created"));
+    console.log(green("✔ Dependencies installed"));
     console.log(`
 Next steps:
   cd ${name}
@@ -90,44 +78,89 @@ Next steps:
 `);
 }
 
-// ------------------------------------------
-// RUN BUNDLER
-// ------------------------------------------
+// BUNDLE
 function runBundler() {
-    const bundler = path.join(process.cwd(), "titan", "bundler.js");
+    const bundler = path.join(process.cwd(), "titan", "bundle.js");
 
     if (fs.existsSync(bundler)) {
-        console.log(cyan("Titan: bundling actions..."));
         execSync(`node ${bundler}`, { stdio: "inherit" });
     } else {
-        console.log(yellow("Warning: cli/bundle.js missing."));
+        console.log(yellow("Warning: titan/bundle.js missing."));
     }
 }
 
 // ------------------------------------------
-// DEV SERVER
+// FULL HOT RELOAD DEV SERVER
 // ------------------------------------------
-function devServer() {
-    console.log(cyan("Titan: generating routes.json & action_map.json..."));
-    execSync("node app/app.js", { stdio: "inherit" });
 
-    // RUN BUNDLER HERE
-    runBundler();
+async function devServer() {
+    console.log(cyan("Titan Dev Mode — Hot Reload Enabled"));
 
-    console.log(cyan("Titan: starting Rust server..."));
+    let rustProcess = null;
 
-    spawn("cargo", ["run"], {
-        cwd: path.join(process.cwd(), "server"),
-        stdio: "inherit",
-        shell: true,
+    function startRust() {
+        // ---- FIX: Proper kill for Windows ----
+        if (rustProcess) {
+            console.log(yellow("[Titan] Killing old Rust server..."));
+
+            if (process.platform === "win32") {
+                spawn("taskkill", ["/PID", rustProcess.pid, "/T", "/F"], {
+                    stdio: "inherit",
+                    shell: true
+                });
+            } else {
+                rustProcess.kill();
+            }
+        }
+
+        // ---- START NEW PROCESS ----
+        rustProcess = spawn("cargo", ["run"], {
+            cwd: path.join(process.cwd(), "server"),
+            stdio: "inherit",
+            shell: true,
+        });
+
+        rustProcess.on("close", (code) => {
+            console.log(red(`[Titan] Rust server exited: ${code}`));
+        });
+    }
+
+    function rebuild() {
+        console.log(cyan("Titan: Regenerating routes..."));
+        execSync("node app/app.js", { stdio: "inherit" });
+
+        console.log(cyan("Titan: Bundling actions..."));
+        runBundler();
+    }
+
+    // First build
+    rebuild();
+    startRust();
+
+    // WATCHER
+    const chokidar = (await import("chokidar")).default;
+
+    const watcher = chokidar.watch("app", { ignoreInitial: true });
+
+    let timer = null;
+
+    watcher.on("all", (event, file) => {
+        if (timer) clearTimeout(timer);
+
+        timer = setTimeout(() => {
+            console.log(yellow(`Change detected → ${file}`));
+
+            rebuild();
+            startRust();
+
+        }, 250);
     });
 }
 
-// ------------------------------------------
+
 // BUILD RELEASE
-// ------------------------------------------
 function buildProd() {
-    console.log(cyan("Titan: generating routes + bundling..."));
+    console.log(cyan("Titan: generate routes + bundle..."));
     execSync("node app/app.js", { stdio: "inherit" });
     runBundler();
 
@@ -138,15 +171,10 @@ function buildProd() {
     });
 }
 
-// ------------------------------------------
 // START PRODUCTION
-// ------------------------------------------
 function startProd() {
     const isWindows = process.platform === "win32";
-
-    const binaryName = isWindows
-        ? "titan-server.exe"
-        : "titan-server"; // Linux / macOS
+    const binaryName = isWindows ? "titan-server.exe" : "titan-server";
 
     const exe = path.join(
         process.cwd(),
@@ -156,14 +184,10 @@ function startProd() {
         binaryName
     );
 
-    execSync(`"${exe}"`, { stdio: "inherit", shell: true });
+    execSync(`"${exe}"`, { stdio: "inherit" });
 }
 
-
-
-// ------------------------------------------
 // ROUTER
-// ------------------------------------------
 switch (cmd) {
     case "init":
         initProject(args[1]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezetgalaxy/titan",
-  "version": "25.11.4",
+  "version": "25.11.6",
   "description": "JavaScript backend framework that compiles your JS into a Rust + Axum server.",
   "license": "ISC",
   "author": "ezetgalaxy",
@@ -46,6 +46,7 @@
     "test": "echo \"No tests specified\""
   },
   "dependencies": {
+    "chokidar": "^5.0.0",
     "esbuild": "^0.27.1"
   }
 }

package/scripts/make_dist.sh

@@ -1,39 +1,71 @@
 #!/usr/bin/env bash
 set -e
-# Create dist folder and copy release binary
-ROOT=$(cd "$(dirname "$0")/.." && pwd)
+
+echo "Building Titan distribution..."
+
+# ---------------------------------------------
+# Resolve directories
+# ---------------------------------------------
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 SERVER_DIR="$ROOT/server"
 DIST_DIR="$ROOT/dist"
+
+# Clean and recreate dist/
 rm -rf "$DIST_DIR"
 mkdir -p "$DIST_DIR"
 
+# ---------------------------------------------
+# Copy release binary titan-server
+# ---------------------------------------------
+RELEASE_PATH="$SERVER_DIR/target/release"
 
-# copy binary
-if [ -f "$SERVER_DIR/target/release/titan-server" ]; then
-cp "$SERVER_DIR/target/release/titan-server" "$DIST_DIR/"
+echo "Looking for titan-server binary..."
+
+if [ -f "$RELEASE_PATH/titan-server" ]; then
+    echo "✓ Found titan-server"
+    cp "$RELEASE_PATH/titan-server" "$DIST_DIR/"
 else
-# on mac/linux after build the binary name may differ by package name
-BIN=$(ls "$SERVER_DIR/target/release" | grep titan-server || true)
-if [ -n "$BIN" ]; then
-cp "$SERVER_DIR/target/release/$BIN" "$DIST_DIR/titan-server"
-fi
-fi
+    echo "Binary not found directly, searching..."
+    BIN=$(ls "$RELEASE_PATH" | grep 'titan-server' || true)
 
+    if [ -n "$BIN" ]; then
+        echo "✓ Found matching binary: $BIN"
+        cp "$RELEASE_PATH/$BIN" "$DIST_DIR/titan-server"
+    else
+        echo "✗ titan-server binary not found in release folder."
+        echo "Did you run: cargo build --release ?"
+        exit 1
+    fi
+fi
 
-# Generate routes.json from project root by inspecting templates (we assume user ran JS bundler to emit routes.build.json)
+# ---------------------------------------------
+# routes.json (JS bundler should generate routes.build.json)
+# ---------------------------------------------
 if [ -f "$ROOT/routes.build.json" ]; then
-cp "$ROOT/routes.build.json" "$DIST_DIR/routes.json"
+    echo "✓ Using routes.build.json"
+    cp "$ROOT/routes.build.json" "$DIST_DIR/routes.json"
 else
-# try default template
-echo "{}" > "$DIST_DIR/routes.json"
+    echo "⚠ No routes.build.json found. Creating empty routes.json"
+    echo "{}" > "$DIST_DIR/routes.json"
 fi
 
-
-# copy handlers if any
+# ---------------------------------------------
+# Copy handlers if they exist
+# ---------------------------------------------
 mkdir -p "$DIST_DIR/handlers"
+
 if [ -d "$ROOT/handlers" ]; then
-cp -r "$ROOT/handlers"/* "$DIST_DIR/handlers/" || true
+    echo "✓ Copying handlers/"
+    cp -r "$ROOT/handlers/"* "$DIST_DIR/handlers/" 2>/dev/null || true
+else
+    echo "⚠ No handlers/ directory found."
 fi
 
-
-echo "Created dist/ with titan-server and routes.json"
+echo ""
+echo "-------------------------------------------"
+echo " ✔ Titan dist/ build complete"
+echo "-------------------------------------------"
+echo "Binary:     dist/titan-server"
+echo "Routes:     dist/routes.json"
+echo "Handlers:   dist/handlers/"
+echo ""

package/templates/app/actions/hello.js

@@ -0,0 +1,6 @@
+function hello(req) {
+    const name = req.name;
+    return { name: name, msg: `Hello ${name}` }
+}
+
+globalThis.hello = hello;

package/templates/app/app.js

@@ -3,8 +3,8 @@ import t from "../titan/titan.js";
 
 
 
+t.post("/hello").action("hello") // pass a json payload { "name": "titan" }
 
-
-t.get("/").reply("Ready to land on Titan 🚀");
+t.get("/").reply("Ready to land on Titan Planet 🚀");
 
 t.start(3000, "Titan Running!");

package/templates/titan/bundle.js

@@ -6,20 +6,29 @@ const root = process.cwd();
 const actionsDir = path.join(root, "app", "actions");
 const outDir = path.join(root, "server", "actions");
 
-fs.mkdirSync(outDir, { recursive: true });
+export async function bundle() {
+  console.log("[Titan] Bundling actions...");
 
-const files = fs.readdirSync(actionsDir).filter(f => f.endsWith(".js"));
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // Clean old bundles
+  for (const file of fs.readdirSync(outDir)) {
+    fs.unlinkSync(path.join(outDir, file));
+  }
+
+  const files = fs.readdirSync(actionsDir).filter(f => f.endsWith(".js"));
 
-(async () => {
   for (const file of files) {
     const entry = path.join(actionsDir, file);
-    const outfile = path.join(outDir, file + "bundle");
 
-    console.log(`Bundling ${entry} → ${outfile}`);
+    // Rust runtime expects `.jsbundle` extension — consistent with previous design
+    const outfile = path.join(outDir, file.replace(".js", ".jsbundle"));
+
+    console.log(`[Titan] Bundling ${entry} → ${outfile}`);
 
     await esbuild.build({
       entryPoints: [entry],
-      bundle: false,
+      bundle: true,
       format: "cjs",
       platform: "neutral",
       outfile,
@@ -27,5 +36,5 @@ const files = fs.readdirSync(actionsDir).filter(f => f.endsWith(".js"));
     });
   }
 
-  console.log("Bundling complete.");
-})();
+  console.log("[Titan] Bundling finished.");
+}

package/templates/titan/dev.js

@@ -0,0 +1,67 @@
+import chokidar from "chokidar";
+import { spawn, execSync } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+import { bundle } from "./bundle.js";
+
+// Required for __dirname in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let serverProcess = null;
+
+function startRustServer() {
+    if (serverProcess) {
+        serverProcess.kill();
+    }
+
+    const serverPath = path.join(process.cwd(), "server");
+
+    serverProcess = spawn("cargo", ["run"], {
+        cwd: serverPath,
+        stdio: "inherit",
+        shell: true
+    });
+
+    serverProcess.on("close", (code) => {
+        console.log(`[Titan] Rust server exited: ${code}`);
+    });
+}
+
+async function rebuild() {
+    console.log("[Titan] Regenerating routes.json & action_map.json...");
+    execSync("node app/app.js", { stdio: "inherit" });
+
+    console.log("[Titan] Bundling JS actions...");
+    await bundle();
+}
+
+async function startDev() {
+    console.log("[Titan] Dev mode starting...");
+
+    // FIRST BUILD
+    await rebuild();
+    startRustServer();
+
+    const watcher = chokidar.watch("app", {
+        ignoreInitial: true
+    });
+
+    let timer = null;
+
+    watcher.on("all", async (event, file) => {
+        if (timer) clearTimeout(timer);
+
+        timer = setTimeout(async () => {
+            console.log(`[Titan] Change detected: ${file}`);
+
+            await rebuild();
+
+            console.log("[Titan] Restarting Rust server...");
+            startRustServer();
+
+        }, 200);
+    });
+}
+
+startDev();