titanpl 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, Ezet Galaxy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+<p align="center">
+  <a href="https://titan-docs-ez.vercel.app/" target="_blank">
+    <img src="https://i.ibb.co/VpBsTg6m/tpl-Logo.png" width="120" alt="TitanPl Logo" />
+  </a>
+</p>
+
+<p align="center">
+   You write zero Rust. TitanPl handles routing, bundling, runtime execution, hot reload, and deployment — <br> all powered by <a href="https://rust-lang.org/">Rust</a> under the hood.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ezetgalaxy/titan">
+    <img src="https://img.shields.io/npm/v/@ezetgalaxy/titan?style=for-the-badge&logo=npm&logoColor=white" />
+  </a>
+
+  <img src="https://img.shields.io/badge/Runtime-Gravity(V8)%20%26%20Rust%20Tokio-1f2937?style=for-the-badge" />
+
+  <img src="https://img.shields.io/badge/Powered%20By%20Rust%20Axum-DEA584?style=for-the-badge&logo=rust&logoColor=black" />
+
+  <a href="https://discord.gg/mPDaTRtP">
+    <img src="https://img.shields.io/badge/Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" />
+  </a>
+
+  <a href="https://x.com/TitanPl">
+    <img src="https://img.shields.io/badge/Follow-000000?style=for-the-badge&logo=x&logoColor=white" />
+  </a>
+
+</p>
+
+
+
+
+<h1> Description
+</h1>
+
+Titan Planet is a JavaScript/TypeScript-first Backend Framework that compiles your application into a single, high-performance native binary. It embeds it's own Gravity (V8) JavaScript runtime directly into a specialized Rust + Axum server.
+
+**TypeScript Precision. JavaScript Simplicity. Native Rust Power. Zero Configuration.**
+
+<p>
+   
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
+  <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black" />
+  <img src="https://img.shields.io/badge/Rust-DEA584?style=for-the-badge&logo=rust&logoColor=black" />
+</p>
+
+  
+## Why Titan?
+
+Titan Planet compiles your JavaScript or TypeScript application into a **single native Rust binary**.
+
+It embeds a V8 runtime inside a Rust + Axum server — giving you:
+
+- ⚡ Native-level performance
+- 📦 Single binary deployment
+- 🧠 Strict TypeScript enforcement
+- 🛡 Zero type errors before runtime
+- 🚀 No DevOps configuration required
+
+Start with pure TypeScript.
+Drop into Rust when you need extreme performance.
+Titan handles the integration automatically.
+
+<p>
+  <a href="https://titan-docs-ez.vercel.app/docs" target="_blank">
+    <img src="https://i.ibb.co/VpBsTg6m/tpl-Logo.png" width="28" style="vertical-align:middle;" />
+    <strong style="vertical-align:middle;"> Documentation</strong>
+</p>
+<p>
+<a href="https://titan-docs-ez.vercel.app/docs/runtime-architecture" target="_blank">
+    <strong style="vertical-align:middle;">Gravity Runtime</strong>
+  </a>
+</p>
+  
+ <p>
+     <a href="https://titan-docs-ez.vercel.app/docs/14-drift" target="_blank">
+    <strong style="vertical-align:middle;">Drift</strong>
+  </a>
+ </p>
+
+# 🚀 Quick Start
+### 1. Prerequisites
+* **Rust** (latest stable): [Install Rust](https://rust-lang.org/tools/install/)
+* **Node.js** (v18+): Required for CLI and JS tooling.
+
+### 2. Install CLI
+```bash
+npm install -g @ezetgalaxy/titan
+```
+
+### 3. Initialize & Run
+Titan guides you through selecting the perfect architecture for your needs.
+
+```bash
+titan init my-app
+```
+
+**Select your language:**
+1.  `JavaScript` (Fast, lightweight)
+2.  `TypeScript` (Strict, typed)
+
+**Select your architecture:**
+1.  `Standard` (Pure JS/TS)
+2.  `Rust + JS/TS (Hybrid)` (High-performance native actions)
+
+This creates one of four isolated environments:
+*   **Standard JS:** Lightweight server, zero Rust overhead.
+*   **Standard TS:** Strict server, zero Rust overhead.
+*   **Hybrid JS:** Full Rust integration + JS flexibility.
+*   **Hybrid TS:** Full Rust integration + TS strictness.
+
+Inside your project:
+```bash
+cd my-app
+titan dev
+```
+
+You'll see the Titan Dev Server spin up:
+```
+  Titan Planet   v26.16.0   [ Dev Mode ]
+
+  Type:        Rust + TS Actions
+  Hot Reload:  Enabled
+  Strict Mode: Active 🛡️
+
+  • Preparing runtime... Done
+  • A new orbit is ready for your app in 0.9s
+  • Your app is now orbiting Titan Planet
+```
+
+
+# ⚡ Hybrid Action System
+
+Titan is unique because it allows you to write endpoints in **JavaScript, TypeScript, and Rust** within the same project.
+
+| Feature | Status | Notes |
+| :--- | :--- | :--- |
+| **Standard JavaScript** | ✅ Stable | Production Ready |
+| **Standard TypeScript** | 🚧 Beta | **Ready for Dev**, Production Under Testing |
+| **Rust + JS (Hybrid)** | 🧪 Experimental | **Dev Only**, Production Under Testing |
+| **Rust + TS (Hybrid)** | 🧪 Experimental | **Dev Only**, Production Under Testing |
+
+### 🔵 TypeScript Actions (`app/actions/hello.ts`)
+Fully typed, strict, and auto-compiled.
+
+```typescript
+import { defineAction } from "../../titan/titan";
+
+interface HelloResponse {
+    message: string;
+    user_name: string;
+}
+
+// "defineAction" provides automatic type inference for "req"
+export const hello = defineAction((req): HelloResponse => {
+    t.log("Handling request with strict types...");
+
+    return { 
+        message: "Hello from TypeScript!",
+        user_name: req.body.name || "Guest"
+    };
+});
+```
+
+### 🟡 JavaScript Actions (`app/actions/hello.js`)
+Perfect for business logic, rapid prototyping, and IO-bound tasks.
+```javascript
+export const hello = defineAction((req) => {
+    t.log("Handling user request...");
+    return { 
+        message: "Hello from JavaScript!",
+        user_id: req.params.id 
+    };
+});
+```
+
+### 🔴 Rust Actions (Beta)
+Perfect for heavy computation, encryption, image processing, or low-level system access.
+> **Note:** The Native Rust Action API is currently in **Beta**.
+```rust
+use axum::{response::{IntoResponse, Json}, http::Request, body::Body};
+use serde_json::json;
+
+pub async fn run(req: Request<Body>) -> impl IntoResponse {
+    let result = heavy_computation();
+    t.log("Processed 1M records in Rust");
+    Json(json!({ "result": result }))
+}
+```
+
+**Titan automatically detects, compiles, and routes all types.**
+* `.ts` files are type-checked and compiled with esbuild.
+* `.js` files are bundled with esbuild.
+* `.rs` files are compiled into the native binary.
+* All share the same `routes.json` configuration.
+
+---
+
+# 🛡️ Strict Type Safety & Error Logs
+
+Titan prioritizes code quality by enforcing **Strict TypeScript** logic during development. 
+
+If `titan dev` detects a type error, the server **will not run**. This ensures you never ship or test broken code.
+
+### Sample Error Output
+When a type error occurs, Titan pauses execution and provides a clear, actionable log:
+
+```text
+[Titan] ❌ TypeScript Error:
+app/actions/payment.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
+
+    10 |    const amount: number = req.body.amount;
+    11 |    
+  > 12 |    processPayment( "100" ); // Error here
+       |    ^^^^^^^^^^^^^^^^^^^^^^^
+
+[Titan] 🛑 Server paused due to type errors. Fix them to resume.
+```
+
+Once fixed, the server automatically resumes.
+
+---
+
+# ✨ Core Capabilities
+
+### 🔌 Unified Runtime API (`t`)
+All actions (JS/TS/Rust) have access to the powerful `t` namespace:
+
+* `t.fetch(url, options)` — High-performance HTTP client
+* `t.log(msg)` — Sandboxed, structured logging
+* `t.jwt.sign / verify` — Fast JWT operations
+* `t.password.hash / verify` — Secure password handling
+* `t.db` — Database access
+---
+
+### 🧩 Extensions System
+Extend the runtime with custom Rust engines using **Titan Extensions**.
+* `titan create ext <name>`: Scaffold a new extension.
+* `titan run ext`: Test your extension in a lightweight harness.
+
+---
+
+# 📦 Deployment
+
+Titan compiles your entire app—JS/TS code, Rust code, and server logic—into a **single executable**.
+
+* **Tiny Docker Images**: Alpine-based, ~20MB compressed.
+* **Instant Startup**: No node_modules overhead.
+* **Secure**: No access to system APIs from JS unless explicitly bridged.
+
+---
+
+
+**To know more read docs 💟 **Titan Planet docs:** https://titan-docs-ez.vercel.app/docs**

package/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/* 
+ * The Titan CLI has been completely rewritten and moved to packages/cli. 
+ * This file remains for backward compatibility and redirects execution to the new CLI.
+ */
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const newCliPath = path.join(__dirname, "packages", "cli", "index.js");
+
+const args = process.argv.slice(2);
+const child = spawn("node", [newCliPath, ...args], {
+  stdio: "inherit",
+  cwd: process.cwd()
+});
+
+child.on("close", (code) => {
+  process.exit(code);
+});

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "titanpl",
+  "version": "1.0.0",
+  "description": "Titan Planet is a JavaScript-first backend framework that embeds JS actions into a Rust + Axum server and ships as a single native binary. Routes are compiled to static metadata; only actions run in the embedded JS runtime. No Node.js. No event loop in production.",
+  "license": "ISC",
+  "author": "ezetgalaxy",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "tit": "./packages/cli/index.js",
+    "titan": "./packages/cli/index.js"
+  },
+  "workspaces": [
+    "packages/*",
+    "testapp"
+  ],
+  "files": [
+    "index.js",
+    "templates/",
+    "titanpl-sdk",
+    "README.md"
+  ],
+  "keywords": [
+    "titan",
+    "titanpl",
+    "t8n",
+    "tpl",
+    "tgrv",
+    "titanjs",
+    "ezetgalaxy",
+    "framework",
+    "javascript",
+    "nodejs",
+    "backend",
+    "web-framework",
+    "api-framework",
+    "rust",
+    "rust-backend",
+    "axum",
+    "boa",
+    "js-to-rust",
+    "server",
+    "high-performance",
+    "native-performance",
+    "microservices",
+    "cli",
+    "esbuild",
+    "modern-backend",
+    "edge-computing",
+    "super-backend"
+  ],
+  "scripts": {
+    "cli-helper": "node ./scripts/cli-helper.mjs",
+    "create-ext": "titan create ext",
+    "init": "rm -rf build && node index.js init build",
+    "build": "cd build && node ../index.js build",
+    "dev": "cd build && node ../index.js dev",
+    "start": "cd build && node ../index.js start",
+    "help": "cd build && node ../index.js help",
+    "update": "cd build && node ../index.js update",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:cov": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "test:e2e:watch": "vitest --config vitest.config.e2e.ts",
+    "test:e2e:ui": "vitest --ui --config vitest.config.e2e.ts",
+    "test:all": "vitest run && vitest run --config vitest.config.e2e.ts"
+  },
+  "dependencies": {
+    "@titanpl/core": "26.16.0",
+    "@titanpl/node": "26.16.0",
+    "chokidar": "^5.0.0",
+    "esbuild": "^0.27.2",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.17",
+    "@vitest/ui": "^4.0.17",
+    "vitest": "^4.0.17"
+  }
+}

package/packages/cli/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { buildCommand } from "./src/commands/build.js";
+import { devCommand } from "./src/commands/dev.js";
+import { startCommand } from "./src/commands/start.js";
+import { migrateCommand } from "./src/commands/migrate.js";
+import { initCommand } from "./src/commands/init.js";
+
+/* -------------------------------------------------------
+ * Resolve __dirname (ESM safe)
+ * ----------------------------------------------------- */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/* -------------------------------------------------------
+ * Colors (Old Titan Theme Style)
+ * ----------------------------------------------------- */
+const cyan = (t) => `\x1b[36m${t}\x1b[0m`;
+const green = (t) => `\x1b[32m${t}\x1b[0m`;
+const yellow = (t) => `\x1b[33m${t}\x1b[0m`;
+const red = (t) => `\x1b[31m${t}\x1b[0m`;
+const bold = (t) => `\x1b[1m${t}\x1b[0m`;
+const gray = (t) => `\x1b[90m${t}\x1b[0m`;
+
+/* -------------------------------------------------------
+ * Version
+ * ----------------------------------------------------- */
+let VERSION = "1.0.0";
+
+try {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
+  );
+  VERSION = pkg.version;
+} catch { }
+
+/* -------------------------------------------------------
+ * Help Output
+ * ----------------------------------------------------- */
+function help() {
+  console.log(`
+${bold(cyan("╭───────────────────────────────────────────────╮"))}
+${bold(cyan("│"))}  🪐 ${bold(cyan("Titan Planet"))} CLI                     ${gray(`v${VERSION}`.padEnd(6, ' '))} ${bold(cyan("│"))}
+${bold(cyan("╰───────────────────────────────────────────────╯"))}
+
+  ${yellow("Usage:")} ${bold("titan <command> [options]")}
+
+  ${bold("Commands:")}
+    ${cyan("init")}      ${gray("Scaffold a new Titan project")}
+    ${cyan("build")}     ${gray("Compile actions and build production dist")}
+    ${cyan("dev")}       ${gray("Start the Gravity Engine in dev/watch mode")}
+    ${cyan("start")}     ${gray("Start the production Gravity Engine")}
+    ${cyan("migrate")}   ${gray("Migrate a legacy project to the new architecture")}
+
+  ${bold("Options:")}
+    ${cyan("-v, --version")}  ${gray("Output the current version")}
+    ${cyan("-h, --help")}     ${gray("Display this help message")}
+
+${gray("  The Titan Planet Engine runs your JS/TS server natively without Node.js. ")}
+  ${cyan("https://titan-docs-ez.vercel.app")}
+`);
+}
+
+/* -------------------------------------------------------
+ * CLI Router
+ * ----------------------------------------------------- */
+const cmd = process.argv[2];
+
+(async () => {
+  try {
+    // -------------------------------------------------------
+    // Legacy Check
+    // -------------------------------------------------------
+    if (cmd !== 'migrate' && cmd !== 'init') {
+      const legacyCargo = path.join(process.cwd(), "server", "Cargo.toml");
+      if (fs.existsSync(legacyCargo)) {
+        console.log(yellow(`\n⚠️ This project uses legacy server architecture. Migration recommended.`));
+        console.log(`Please run: ${bold(cyan('titan migrate'))}\n`);
+        process.exit(1);
+      }
+    }
+
+    // -------------------------------------------------------
+    // Old tit / titan detection note
+    // -------------------------------------------------------
+    const scriptBase = path.basename(process.argv[1]);
+    if (scriptBase === 'tit') {
+      console.log(yellow(`\n⚠️ [Notice]: \`tit\` is deprecated. Please use \`titan\` instead.\n`));
+    }
+
+
+    switch (cmd) {
+      case "init": {
+        const projectName = process.argv[3];
+        let template = null;
+        const tIndex = process.argv.indexOf("-t") !== -1 ? process.argv.indexOf("-t") : process.argv.indexOf("--template");
+        if (tIndex !== -1 && process.argv[tIndex + 1]) {
+          template = process.argv[tIndex + 1];
+        }
+        await initCommand(projectName, template);
+        break;
+      }
+
+      case "build":
+        console.log(cyan("→ Building Titan project..."));
+        await buildCommand();
+        console.log(green("✔ Build complete"));
+        break;
+
+      case "dev":
+        await devCommand();
+        break;
+
+      case "start":
+        console.log(cyan("→ Starting Titan Server..."));
+        startCommand();
+        break;
+
+      case "migrate":
+        await migrateCommand();
+        break;
+
+      case "--version":
+      case "-v":
+      case "version":
+        console.log(cyan(`Titan CLI v${VERSION}`));
+        break;
+
+      default:
+        help();
+    }
+  } catch (err) {
+    console.error(red("✖ Titan CLI Error"));
+    console.error(gray(err?.message || err));
+    process.exit(1);
+  }
+})();

package/templates/common/.env

@@ -0,0 +1 @@
+TITAN_DEV=1

package/templates/common/Dockerfile

@@ -0,0 +1,66 @@
+# ================================================================
+# STAGE 1 — Build TitanPl
+# ================================================================
+FROM node:20.20.0-slim AS builder
+
+WORKDIR /app
+
+# Install native dependencies in case of native modules or hybrids
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates build-essential pkg-config libssl-dev git bash \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV NODE_ENV=production
+
+# ---------- Node Dependencies ----------
+COPY package.json package-lock.json* ./
+RUN npm install
+
+# ---------- Copy Project ----------
+COPY . .
+
+# Run the Titan build command (compiles dist/)
+RUN npx titan build
+
+# ================================================================
+# STAGE 2 — Gravity Engine (Production Ready)
+# ================================================================
+FROM node:20.20.0-slim
+
+WORKDIR /app
+
+# Ensure we have required OS-level certs if doing network fetching
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# ---- Copy Production package.json and install ONLY dependencies ----
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev
+
+# ---- Copy Dist Build from Builder ----
+COPY --from=builder /app/dist ./dist
+
+# ---------------- OPTIONAL APP FOLDERS ----------------
+# Static assets
+# COPY --from=builder /app/app/static ./static
+
+# Public assets
+# COPY --from=builder /app/app/public ./public
+
+# DB
+# COPY --from=builder /app/app/db ./db
+
+# ---- Create User After Copy ----
+RUN useradd -m titan && chown -R titan:titan /app
+USER titan
+
+# ---- Platform Defaults ----
+ENV HOST=0.0.0.0
+ENV PORT=5100
+ENV TITAN_DEV=0
+
+EXPOSE 5100
+
+# ---- Force Foreground Process via Titan CLI ----
+CMD ["npx", "titan", "start"]

package/templates/common/_dockerignore

@@ -0,0 +1,35 @@
+node_modules
+npm-debug.log
+.git
+.gitignore
+
+package-lock.json
+yarn.lock
+
+# Titan Gravity Engine
+dist/
+.titan/
+.ext/
+
+deploy/
+
+# Rust Build Artifacts
+server/target/
+Cargo.lock
+
+# OS Files
+.DS_Store
+Thumbs.db
+*.tmp
+*.bak
+
+# Environment & Secrets
+.env
+.env.local
+.env.*.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo

package/templates/common/_gitignore

@@ -0,0 +1,33 @@
+# Node & Packages
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json
+yarn.lock
+
+# Titan Gravity Engine (Auto-generated - DO NOT COMMIT)
+dist/
+.titan/
+.ext/
+.env
+
+# Rust Build Artifacts (If using Hybrid)
+server/target/
+Cargo.lock
+
+# OS Files
+.DS_Store
+Thumbs.db
+*.tmp
+*.bak
+
+# Environment & Secrets
+.env.local
+.env.*.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo