titanpl-sdk 0.0.7

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,101 @@
+
+# 🛠️ Titan SDK
+
+**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)
+
+---
+
+## 🌌 Overview
+
+**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. 
+
+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
+
+- **💎 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.
+
+---
+
+## 🚀 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.
+
+### 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.
+
+### Usage:
+
+```bash
+# Inside your extension directory
+npx titan-sdk
+```
+
+---
+
+## ⌨️ Enabling IntelliSense
+
+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
+    ```
+
+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); // Autocomplete works!
+  return { status: "ok" };
+}
+```
+
+---
+
+## 🧱 What's Included? (Types Only)
+
+The SDK provides types for the native APIs provided by the Titan Planet engine:
+
+- **`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
+
+- **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/ezet-galaxy/-ezetgalaxy-titan">Titan Planet</a> ecosystem.
+</p>

package/bin/run.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Helper for colors
+const cyan = (t) => `\x1b[36m${t}\x1b[0m`;
+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"));
+
+    // 1. Validate we are in an extension directory
+    const cwd = process.cwd();
+    const manifestPath = path.join(cwd, "titan.json");
+    if (!fs.existsSync(manifestPath)) {
+        console.log(red("Error: titan.json not found. Run this command inside your extension folder."));
+        process.exit(1);
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const name = manifest.name;
+    console.log(green(`Extension: ${name}`));
+
+    // 2. Build Native Logic (if properly set up)
+    const nativeDir = path.join(cwd, "native");
+    if (fs.existsSync(nativeDir) && fs.existsSync(path.join(nativeDir, "Cargo.toml"))) {
+        console.log(cyan("Building native Rust module..."));
+        try {
+            execSync("cargo build --release", { cwd: nativeDir, stdio: "inherit" });
+        } catch (e) {
+            console.log(red("Failed to build native module."));
+            process.exit(1);
+        }
+    }
+
+    // 3. Create a Test Harness (Mini Titan Project)
+    const runDir = path.join(cwd, ".titan_test_run");
+    if (fs.existsSync(runDir)) {
+        try {
+            fs.rmSync(runDir, {
+                recursive: true,
+                force: true,
+                maxRetries: 10,
+                retryDelay: 100
+            });
+        } catch (e) {
+            console.log(yellow(`Warning: Could not fully clean ${runDir}. Proceeding anyway...`));
+        }
+    }
+
+    // Ensure runDir exists (sometimes rmSync + mkdirSync fails on Windows due to locks)
+    if (!fs.existsSync(runDir)) {
+        fs.mkdirSync(runDir, { recursive: true });
+    }
+
+    // Create app structure
+    const appDir = path.join(runDir, "app");
+    fs.mkdirSync(appDir);
+
+    // Create actions folder (required by Titan build)
+    const actionsDir = path.join(appDir, "actions");
+    fs.mkdirSync(actionsDir);
+
+    // Copy titan/ and server/ from templates
+    const templatesDir = path.join(__dirname, "..", "templates");
+
+    const titanSrc = path.join(templatesDir, "titan");
+    const titanDest = path.join(runDir, "titan");
+    if (fs.existsSync(titanSrc)) {
+        console.log(cyan("→ Setting up Titan runtime..."));
+        copyDir(titanSrc, titanDest);
+        // Double check titan.js exists
+        if (!fs.existsSync(path.join(titanDest, "titan.js"))) {
+            console.log(red(`Error: Failed to copy titan.js to ${titanDest}`));
+            process.exit(1);
+        }
+    } 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)) {
+        console.log(cyan("→ Setting up Titan server..."));
+        copyDir(serverSrc, serverDest);
+    } else {
+        console.log(red(`Error: Server templates not found at ${serverSrc}`));
+        process.exit(1);
+    }
+
+    // Create package.json for the test harness
+    const pkgJson = {
+        "type": "module"
+    };
+    fs.writeFileSync(path.join(runDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+
+    // Create 'node_modules' to link the extension
+    const nmDir = path.join(runDir, "node_modules");
+    fs.mkdirSync(nmDir);
+
+    // Link current extension to node_modules/NAME
+    // Use junction for Windows compat without admin rights
+    const extDest = path.join(nmDir, name);
+    try {
+        fs.symlinkSync(cwd, extDest, "junction");
+    } catch (e) {
+        // Fallback to copy if link fails
+        console.log(yellow("Linking failed, copying extension files..."));
+        copyDir(cwd, extDest);
+    }
+
+    // Create a test action in app/actions/test.js
+    const testAction = `export const test = (req) => {
+    const ext = t["${name}"];
+    
+    const results = {
+        extension: "${name}",
+        loaded: !!ext,
+        methods: ext ? Object.keys(ext) : [],
+        timestamp: new Date().toISOString()
+    };
+    
+    if (ext && ext.hello) {
+        try {
+            results.hello_test = ext.hello("World");
+        } catch(e) {
+            results.hello_error = String(e);
+        }
+    }
+    
+    if (ext && ext.calc) {
+        try {
+            results.calc_test = ext.calc(15, 25);
+        } catch(e) {
+            results.calc_error = String(e);
+        }
+    }
+    
+    return results;
+};
+`;
+
+    fs.writeFileSync(path.join(actionsDir, "test.js"), testAction);
+
+    // Create a simple test script in app/app.js
+    // This script will be executed by Titan
+    const testScript = `import t from "../titan/titan.js";
+import "${name}";
+
+// Extension test harness for: ${name}
+const ext = t["${name}"];
+
+console.log("---------------------------------------------------");
+console.log("Testing Extension: ${name}");
+console.log("---------------------------------------------------");
+
+if (!ext) {
+    console.log("ERROR: Extension '${name}' not found in global 't'.");
+} else {
+    console.log("✓ Extension loaded successfully!");
+    console.log("✓ Available methods:", Object.keys(ext).join(", "));
+    
+    // Try 'hello' if it exists
+    if (typeof ext.hello === 'function') {
+        console.log("\\nTesting ext.hello('Titan')...");
+        try {
+           const res = ext.hello("Titan");
+           console.log("✓ Result:", res);
+        } catch(e) {
+           console.log("✗ Error:", e.message);
+        }
+    }
+
+    // Try 'calc' if it exists
+    if (typeof ext.calc === 'function') {
+        console.log("\\nTesting ext.calc(10, 20)...");
+        try {
+            const res = ext.calc(10, 20);
+            console.log("✓ Result:", res);
+        } catch(e) {
+            console.log("✗ Error:", e.message);
+        }
+    }
+}
+
+console.log("---------------------------------------------------");
+console.log("✓ Test complete!");
+console.log("\\n📍 Routes:");
+console.log("  GET  http://localhost:3000/      → Test harness info");
+console.log("  GET  http://localhost:3000/test  → Extension test results (JSON)");
+console.log("---------------------------------------------------\\n");
+
+// Create routes
+t.get("/test").action("test");
+t.get("/").reply("🚀 Extension Test Harness for ${name}\\n\\nVisit /test to see extension test results");
+
+await t.start(3000, "Titan Extension Test Running!");
+`;
+
+    fs.writeFileSync(path.join(appDir, "app.js"), testScript);
+
+    // Build the app (bundle actions)
+    console.log(cyan("Building test app..."));
+    try {
+        // Ensure we are in runDir and the file exists
+        const appJsPath = path.join(runDir, "app", "app.js");
+        if (!fs.existsSync(appJsPath)) {
+            throw new Error(`app/app.js missing at ${appJsPath}`);
+        }
+
+        execSync("node app/app.js --build", {
+            cwd: runDir,
+            stdio: "inherit",
+            env: { ...process.env, NODE_OPTIONS: "--no-warnings" }
+        });
+    } catch (e) {
+        console.log(red("Failed to build test app. This is expected if your extension has errors."));
+        // Don't exit here, attempt to continue to show runtime errors if possible
+    }
+
+    // 4. Run Titan Server using cargo run (like dev mode)
+    console.log(green("\x1b[1m\n>>> STARTING EXTENSION TEST >>>\n\x1b[0m"));
+
+    const serverDir = path.join(runDir, "server");
+
+    try {
+        execSync("cargo run", { cwd: serverDir, stdio: "inherit" });
+    } catch (e) {
+        console.log(red("Runtime exited."));
+    }
+}
+
+run();

package/index.d.ts

@@ -0,0 +1,46 @@
+export { };
+
+declare global {
+    /**
+     * Titan Runtime Global Object
+     */
+    const t: Titan.Runtime;
+}
+
+export namespace Titan {
+    interface Runtime {
+        /**
+         * Log messages to the Titan console
+         */
+        log: LogInterface;
+
+        /**
+         * Read file content
+         */
+        read(path: string): string;
+        
+        /**
+         * Fetch API wrapper
+         */
+        fetch(url: string, options?: any): Promise<any>;
+
+        /**
+         * Database operations
+         */
+        db: {
+            query(sql: string, params?: any[]): Promise<any>;
+        };
+
+        /**
+         * Titan Extensions
+         */
+        [key: string]: any;
+    }
+
+    interface LogInterface {
+        (...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    }
+}

package/index.js

@@ -0,0 +1,5 @@
+// Titan SDK
+// This package is primarily for type definitions and development tools.
+// The 't' object is injected globally by the Titan runtime.
+
+export const VERSION = "0.0.1";

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "titanpl-sdk",
+    "version": "0.0.7",
+    "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": {
+        "titanpl-sdk": "./bin/run.js"
+    },
+    "files": [
+        "bin/",
+        "templates/",
+        "titan",
+        "index.js",
+        "index.d.ts",
+        "README.md"
+    ],
+    "keywords": [
+        "titan",
+        "titan-planet",
+        "titanpl-sdk",
+        "ezetgalaxy",
+        "types",
+        "typescript",
+        "intellisense",
+        "sdk",
+        "backend-sdk",
+        "extension-development"
+    ],
+    "license": "ISC"
+}

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/**/*"
+    ]
+}