titan-sdk 0.0.3 → 0.0.5

package/README.md

@@ -1,7 +1,7 @@
 
 # 🛠️ Titan SDK
 
-**Empower your Titan Planet development with first-class type safety and elite developer tools.**
+**The Developer Toolkit for Titan Planet. Type safety, IntelliSense, and Extension Testing.**
 
 [![npm version](https://img.shields.io/npm/v/titan-sdk.svg?style=flat-square)](https://www.npmjs.com/package/titan-sdk)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://opensource.org/licenses/ISC)
@@ -10,97 +10,92 @@
 
 ## 🌌 Overview
 
-**Titan SDK** is the official developer toolkit for [Titan Planet](https://github.com/ezetgalaxy/titan). It provides the glue between your JavaScript actions and the high-performance Rust runtime, ensuring you have full IntelliSense, type safety, and debugging capabilities.
+**Titan SDK** is NOT the runtime engine itself. It is a **development-only toolkit** designed to bridge the gap between your local coding environment and the native Titan Planet binary. 
 
-Whether you are building standard API actions or complex extensions, Titan SDK is your essential companion.
+It provides the necessary **Type Definitions** to make your IDE understand the global `t` object and a **Lite Test Harness** to verify your extensions before they ever touch a production binary.
+
+> **Note:** The actual implementation of `t.log`, `t.fetch`, and other APIs are embedded directly into the [Titan Planet Binary](https://github.com/ezet-galaxy/-ezetgalaxy-titan). This SDK simply provides the "blueprints" (types) and a "sandbox" (test runner).
 
 ---
 
 ## ✨ Features
 
-- **💎 Elite IntelliSense**: Full TypeScript definitions for the global `t` object.
-- **🛡️ Type Safety**: Prevent runtime errors with compile-time checks for `t.log`, `t.fetch`, `t.db`, and more.
-- **🔌 Extension Support**: Tools and types for building custom extensions that plug directly into the Titan Rust engine.
-- **🚀 Zero Overhead**: Designed to be a development-only dependency that maximizes productivity without bloating your production binary.
+- **💎 Blueprint Types (IntelliSense)**: Provides the full TypeScript `index.d.ts` for the global `t` object so you get autocomplete in VS Code and other editors.
+- **🛡️ Static Validation**: Catch parameter mismatches and typos in `t.log`, `t.fetch`, `t.db`, etc., during development.
+- **🔌 Extension Test Harness**: A "lite" version of the Titan runtime that simulates the native environment to test extensions in isolation.
+- **🚀 Zero Production Trace**: This is a `devDependencies` package. It never ships with your binary, keeping your production footprint at literal zero.
 
 ---
 
-## 🚀 Getting Started
+## 🚀 The Test Harness (Lite Runtime)
+
+The SDK includes a specialized **Test Runner** (`titan-sdk`). This is a "lite" version of the Titan ecosystem that acts as a bridge for developers.
 
-### Installation
+### How it works:
+When you run the SDK in an extension folder, it:
+1.  **Scaffolds a Virtual Project**: Creates a temporary, minimal Titan environment in `.titan_test_run`.
+2.  **Native Compilation**: Automatically builds your native Rust code (`native/`) if it exists.
+3.  **Hot-Linking**: Junctions your local extension into the virtual project's `node_modules`.
+4.  **Verification**: Generates a test suite that attempts to call your extension's methods via the real `t` object inside the sandbox.
 
-Add the SDK to your Titan project:
+### Usage:
 
 ```bash
-npm install --save-dev titan-sdk
+# Inside your extension directory
+npx titan-sdk
 ```
 
-### Enable IntelliSense
+---
 
-To get full autocomplete for the Titan runtime APIs, simply create a `tsconfig.json` or `jsconfig.json` in your project root:
+## ⌨️ Enabling IntelliSense
 
-```json
-{
-  "compilerOptions": {
-    "types": ["titan-sdk"]
-  }
-}
-```
+Since the `t` object is injected globally by the Titan engine at runtime, your IDE won't recognize it by default. The SDK fixes this.
+
+1.  **Install the SDK**:
+    ```bash
+    npm install --save-dev titan-sdk
+    ```
 
-Now, when you type `t.` in your actions, you'll see everything available:
+2.  **Configure Types**:
+    Create or update `jsconfig.json` (or `tsconfig.json`) in your project root:
+    ```json
+    {
+      "compilerOptions": {
+        "types": ["titan-sdk"]
+      }
+    }
+    ```
 
+Now your editor will treat `t` as a first-class citizen:
 ```js
 export function myAction(req) {
-  t.log.info("Request received", req.path);
-  
-  // Fully typed db queries!
-  const data = t.db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
-  
-  return data;
+  t.log.info("Request received", req.path); // Autocomplete works!
+  return { status: "ok" };
 }
 ```
 
 ---
 
-## 🔧 Core APIs Powered by SDK
-
-The SDK provides types for the entire `t` namespace:
+## 🧱 What's Included? (Types Only)
 
-- **`t.log`**: Structured logging (info, warn, error).
-- **`t.fetch`**: High-performance Rust-native fetch wrapper.
-- **`t.db`**: Native PostgreSQL interface for extreme speed.
-- **`t.read`**: Optimized file system access.
-- **`t.jwt`**: Built-in JWT handling (if enabled).
+The SDK provides types for the native APIs provided by the Titan Planet engine:
 
----
-
-## 🧩 Building Extensions
-
-Titan SDK allows you to define types for your own extensions. 
-
-```typescript
-// Define your extension types
-declare global {
-    namespace Titan {
-        interface Runtime {
-            myCustomTool: {
-                doSomething: () => void;
-            };
-        }
-    }
-}
-```
+- **`t.log`**: Standardized logging that appears in the Titan binary console.
+- **`t.fetch`**: Types for the high-performance Rust-native network stack.
+- **`t.db`**: Interface for the native PostgreSQL driver.
+- **`t.read`**: Definitions for optimized filesystem reads.
+- **`t.jwt` / `t.password`**: Security helper types.
 
 ---
 
 ## 🌍 Community & Documentation
 
-- **Documentation**: [Titan Planet Docs](https://titan-docs-ez.vercel.app/docs)
-- **Author**: [ezetgalaxy](https://github.com/ezetgalaxy)
-- **Ecosystem**: [Titan Planet](https://github.com/ezetgalaxy/titan)
+- **Core Framework**: [Titan Planet](https://github.com/ezet-galaxy/-ezetgalaxy-titan)
+- **Official Docs**: [Titan Planet Docs](https://titan-docs-ez.vercel.app/docs)
+- **Author**: [ezetgalaxy](https://github.com/ezet-galaxy)
 
 ---
 
 <p align="center">
-  Built with ❤️ for the <a href="https://github.com/ezetgalaxy/titan">Titan Planet</a> ecosystem.
+  Built with ❤️ for the <a href="https://github.com/ezet-galaxy/-ezetgalaxy-titan">Titan Planet</a> ecosystem.
 </p>

package/bin/run.js

@@ -13,6 +13,19 @@ const green = (t) => `\x1b[32m${t}\x1b[0m`;
 const red = (t) => `\x1b[31m${t}\x1b[0m`;
 const yellow = (t) => `\x1b[33m${t}\x1b[0m`;
 
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const file of fs.readdirSync(src)) {
+        const srcPath = path.join(src, file);
+        const destPath = path.join(dest, file);
+        if (fs.lstatSync(srcPath).isDirectory()) {
+            copyDir(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
 function run() {
     console.log(cyan("Titan SDK: Test Runner"));
 
@@ -56,19 +69,24 @@ function run() {
     fs.mkdirSync(actionsDir);
 
     // Copy titan/ and server/ from templates
-    const repoRoot = path.resolve(__dirname, "..", "..");
-    const templatesDir = path.join(repoRoot, "templates");
+    const templatesDir = path.join(__dirname, "..", "templates");
 
     const titanSrc = path.join(templatesDir, "titan");
     const titanDest = path.join(runDir, "titan");
     if (fs.existsSync(titanSrc)) {
-        fs.cpSync(titanSrc, titanDest, { recursive: true });
+        copyDir(titanSrc, titanDest);
+    } else {
+        console.log(red(`Error: Titan templates not found at ${titanSrc}`));
+        process.exit(1);
     }
 
     const serverSrc = path.join(templatesDir, "server");
     const serverDest = path.join(runDir, "server");
     if (fs.existsSync(serverSrc)) {
-        fs.cpSync(serverSrc, serverDest, { recursive: true });
+        copyDir(serverSrc, serverDest);
+    } else {
+        console.log(red(`Error: Server templates not found at ${serverSrc}`));
+        process.exit(1);
     }
 
     // Create package.json for the test harness
@@ -89,7 +107,7 @@ function run() {
     } catch (e) {
         // Fallback to copy if link fails
         console.log(yellow("Linking failed, copying extension files..."));
-        fs.cpSync(cwd, extDest, { recursive: true });
+        copyDir(cwd, extDest);
     }
 
     // Create a test action in app/actions/test.js
@@ -138,7 +156,6 @@ console.log("---------------------------------------------------");
 
 if (!ext) {
     console.log("ERROR: Extension '${name}' not found in global 't'.");
-    console.log("Make sure your extension's package.json has 'type': 'commonjs'");
 } else {
     console.log("✓ Extension loaded successfully!");
     console.log("✓ Available methods:", Object.keys(ext).join(", "));
@@ -177,7 +194,7 @@ console.log("---------------------------------------------------\\n");
 t.get("/test").action("test");
 t.get("/").reply("🚀 Extension Test Harness for ${name}\\n\\nVisit /test to see extension test results");
 
-t.start(3000, "Titan Extension Test Running!");
+await t.start(3000, "Titan Extension Test Running!");
 `;
 
     fs.writeFileSync(path.join(appDir, "app.js"), testScript);
@@ -188,11 +205,10 @@ t.start(3000, "Titan Extension Test Running!");
         execSync("node app/app.js --build", { cwd: runDir, stdio: "inherit" });
     } catch (e) {
         console.log(red("Failed to build test app."));
-        console.log(yellow("This is expected if your extension has errors."));
     }
 
     // 4. Run Titan Server using cargo run (like dev mode)
-    console.log(cyan("Starting Titan Runtime..."));
+    console.log(green("\x1b[1m\n>>> STARTING EXTENSION TEST >>>\n\x1b[0m"));
 
     const serverDir = path.join(runDir, "server");
 

package/package.json

@@ -1,13 +1,21 @@
 {
     "name": "titan-sdk",
-    "version": "0.0.3",
-    "description": "Developer SDK and Type Definitions for Titan Planet — the high-performance Rust-powered JavaScript backend framework. Includes IntelliSense support and extension building tools.",
+    "version": "0.0.5",
+    "description": "Development SDK for Titan Planet. Provides TypeScript type definitions for the global 't' runtime object and a 'lite' test-harness runtime for building and verifying extensions.",
     "main": "index.js",
     "type": "module",
     "types": "index.d.ts",
     "bin": {
         "titan-sdk": "./bin/run.js"
     },
+    "files": [
+        "bin/",
+        "templates/",
+        "titan",
+        "index.js",
+        "index.d.ts",
+        "README.md"
+    ],
     "keywords": [
         "titan",
         "titan-planet",

package/templates/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+npm-debug.log
+.git

package/templates/Dockerfile

@@ -0,0 +1,53 @@
+# ================================================================
+# STAGE 1 — Build Titan (JS → Rust)
+# ================================================================
+FROM rust:1.91.1 AS builder
+
+# Install Node for Titan CLI + bundler
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs
+
+# Install Titan CLI (latest)
+RUN npm install -g @ezetgalaxy/titan@latest
+
+WORKDIR /app
+
+# Copy project files
+COPY . .
+
+# Install JS dependencies (needed for Titan DSL + bundler)
+RUN npm install
+
+# Build Titan metadata + bundle JS actions
+RUN titan build
+
+# Build Rust binary
+RUN cd server && cargo build --release
+
+
+
+# ================================================================
+# STAGE 2 — Runtime Image (Lightweight)
+# ================================================================
+FROM debian:stable-slim
+
+WORKDIR /app
+
+# Copy Rust binary from builder stage
+COPY --from=builder /app/server/target/release/server ./titan-server
+
+# Copy Titan routing metadata
+COPY --from=builder /app/server/routes.json ./routes.json
+COPY --from=builder /app/server/action_map.json ./action_map.json
+
+# Copy Titan JS bundles
+RUN mkdir -p /app/actions
+COPY --from=builder /app/server/actions /app/actions
+
+COPY --from=builder /app/db /app/assets
+
+# Expose Titan port
+EXPOSE 3000
+
+# Start Titan
+CMD ["./titan-server"]

package/templates/app/actions/hello.js

@@ -0,0 +1,5 @@
+export const hello = (req) => {
+   return {
+        message: `Hello from Titan ${req.body.name}`,
+    };
+}

package/templates/app/app.js

@@ -0,0 +1,10 @@
+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 Planet 🚀");
+
+t.start(3000, "Titan Running!");

package/templates/app/titan.d.ts

@@ -0,0 +1,87 @@
+/**
+ * TITAN TYPE DEFINITIONS
+ * ----------------------
+ * These types are globally available in your Titan project.
+ */
+
+/**
+ * The Titan Request Object passed to actions.
+ */
+interface TitanRequest {
+    body: any;
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    headers: {
+        host?: string;
+        "content-type"?: string;
+        "user-agent"?: string;
+        authorization?: string;
+        [key: string]: string | undefined;
+    };
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+
+interface DbConnection {
+    /**
+     * Execute a SQL query.
+     * @param sql The SQL query string.
+     * @param params (Optional) Parameters for the query ($1, $2, etc).
+     */
+    query(sql: string, params?: any[]): any[];
+}
+
+/**
+ * Define a Titan Action with type inference.
+ * @example
+ * export const hello = defineAction((req) => {
+ *   return req.headers;
+ * });
+ */
+declare function defineAction<T>(actionFn: (req: TitanRequest) => T): (req: TitanRequest) => T;
+
+/**
+ * Titan Runtime Utilities
+ */
+declare const t: {
+    /**
+     * Log messages to the server console with Titan formatting.
+     */
+    log(...args: any[]): void;
+
+    /**
+     * Read a file contents as string.
+     * @param path Relative path to the file from project root.
+     */
+    read(path: string): string;
+
+    fetch(url: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        headers?: Record<string, string>;
+        body?: string | object;
+    }): {
+        ok: boolean;
+        status?: number;
+        body?: string;
+        error?: string;
+    };
+
+    jwt: {
+        sign(
+            payload: object,
+            secret: string,
+            options?: { expiresIn?: string | number }
+        ): string;
+        verify(token: string, secret: string): any;
+    };
+
+    password: {
+        hash(password: string): string;
+        verify(password: string, hash: string): boolean;
+    };
+
+    db: {
+        connect(url: string): DbConnection;
+    };
+};
+

package/templates/jsconfig.json

@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+        "module": "esnext",
+        "target": "esnext",
+        "checkJs": false,
+        "noImplicitAny": false,
+        "allowJs": true,
+        "moduleResolution": "node",
+        "baseUrl": ".",
+        "paths": {
+            "*": [
+                "./app/*"
+            ]
+        }
+    },
+    "include": [
+        "app/**/*"
+    ]
+}