titanpl 3.0.0 → 4.0.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://titan-docs-ez.vercel.app/" target="_blank">
+  <a href="https://titanpl.vercel.app/" target="_blank">
     <img src="https://i.ibb.co/VpBsTg6m/tpl-Logo.png" width="120" alt="TitanPl Logo" />
   </a>
 </p>
@@ -237,15 +237,59 @@ Extend the runtime with custom Rust engines using **Titan Extensions**.
 
 ---
 
-# 📦 Deployment
+# 📦 Building & Deployment
 
-Titan compiles your entire app—JS/TS code, Rust code, and server logic—into a **single executable**.
+Titan offers a unified build system that packages your JS/TS code, assets, and the native engine into a single, self-contained `build/` directory.
 
-* **Tiny Docker Images**: Alpine-based, ~20MB compressed.
-* **Instant Startup**: No node_modules overhead.
-* **Secure**: No access to system APIs from JS unless explicitly bridged.
+### 1. Production Build
+Run this command from your project root:
+```bash
+titan build --release
+```
+This will:
+* Bundle your actions into optimized `.jsbundle` files.
+* Extract all required Titan extensions and native libraries to `.ext/`.
+* Copy your `public/`, `static/`, and other configured assets.
+* Generate a `titan-server` executable in the `build/` folder.
+
+### 2. Run the Build
+```bash
+cd build
+./titan-server
+```
+Your application is now running as a standalone native server.
+
+### 🐳 Docker Deployment
+The `titan build --release` command is optimized for Docker. Your `Dockerfile` can be as simple as:
+
+```dockerfile
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY . .
+RUN npm install --include=optional
+RUN npx titan build --release
+
+FROM ubuntu:24.04
+WORKDIR /app
+COPY --from=builder /app/build .
+CMD ["./titan-server", "run", "dist"]
+```
+This produces a tiny, high-performance production image with zero `node_modules`.
+
+### 🛠 Configuration (`tanfig.json`)
+You can customize the build process in your `tanfig.json`:
+```json
+{
+  "build": {
+    "purpose": "deploy",
+    "files": ["public", "db", "secrets"]
+  }
+}
+```
+* **`purpose`**: Use `deploy` to skip `node_modules` junctions for the smallest possible footprint.
+* **`files`**: List any extra folders you want included in the `build/` output.
 
 ---
 
 
-**To know more read docs 💟 **Titan Planet docs:** https://titan-docs-ez.vercel.app/docs**
+**To know more read docs 💟 **Titan Planet docs:** https://titanpl.vercel.app/docs**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "titanpl",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "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",

package/packages/cli/README.md

@@ -5,13 +5,30 @@ The command-line interface (CLI) for Titan Planet. It provides the `titan` and `
 ## What it works (What it does)
 The CLI is responsible for bridging your JavaScript codebase with the underlying Rust/Axum engine. It handles scaffolding, compiling JS actions, generating metadata, and running the server.
 
+## Commands
+
+| Command | Arguments | Description |
+| :--- | :--- | :--- |
+| `init` | `<dir>` | Initialize a new Titan project in the specified directory. |
+| `dev` | | Start the development server with hot-reload and strict type checking. |
+| `build` | | Bundle JavaScript/TypeScript actions into `.jsbundle` files. |
+| `build` | `--release` | Create a self-contained production bundle in `build/` (incl. engine). |
+| `start` | | Start the Titan server (checks for `build/` or local engine). |
+| `update` | | Update the local engine to the latest version. |
+| `ext create` | `<name>` | Scaffold a new native Extension. |
+| `ext run` | | Run the current extension in a test harness. |
+| `help` | | Show available commands and options. |
+
 ## How it works
 You can install this package globally or use it via your package runner (e.g., `npx`). Alternatively, you can install it as a dev dependency in your project.
 
 ```bash
-npx titan help
+npm install -g @titanpl/cli
+titan help
 ```
 
 It parses your application source code, coordinates with `@titanpl/packet` to build the required JS endpoints, and then spins up the pre-compiled native core engine for your OS.
 
-**Important Note:** Currently, Titan Planet and its entire package ecosystem are only for Windows. The Linux version is in development (dev only) for the new architecture and will be launched later.
+**Note:** All commands now prioritize `tanfig.json` for project configuration.
+
+**Note on Platform Architecture:** Titan Planet's new v2 architecture supports Windows and Linux (incl. Docker). MacOS support is in active development.

package/packages/cli/index.js

@@ -53,7 +53,7 @@ ${bold(cyan("╰─────────────────────
   ${bold("Commands:")}
     ${cyan("init")}      ${gray("Scaffold a new Titan project")}
     ${cyan("create")}    ${gray("Create a new project or extension (e.g. 'titan create ext my-ext')")}
-    ${cyan("build")}     ${gray("Compile actions and build production dist")}
+    ${cyan("build")}     ${gray("Compile actions and build production dist. Use --release or -r for a production-ready folder.")}
     ${cyan("dev")}       ${gray("Start the Gravity Engine in dev/watch mode")}
     ${cyan("start")}     ${gray("Start the production Gravity Engine")}
     ${cyan("update")}    ${gray("Update an existing project to latest Titan version")}
@@ -122,9 +122,10 @@ const cmd = process.argv[2];
       }
 
       case "build":
-        console.log(cyan("→ Building Titan project..."));
-        await buildCommand();
-        console.log(green("✔ Build complete"));
+        const isRelease = process.argv.includes("--release") || process.argv.includes("-r");
+        console.log(cyan(`→ Building Titan project${isRelease ? " (Release mode)" : ""}...`));
+        await buildCommand(isRelease);
+        console.log(green(`✔ ${isRelease ? "Release" : "Build"} complete`));
         break;
 
       case "dev":

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/cli",
-  "version": "3.0.0",
+  "version": "5.0.5",
   "description": "The unified CLI for Titan Planet. Use it to create, manage, build, and deploy high-performance backend projects.",
   "keywords": [
     "titanpl",
@@ -12,8 +12,16 @@
   "author": "ezetgalaxy",
   "type": "module",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "src/",
+    "templates/",
+    "README.md"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepack": "node -e \"const fs=require('fs');const p=require('path');const src=p.resolve(__dirname,'..','..','templates');const dest=p.resolve(__dirname,'templates');if(fs.existsSync(src)&&!fs.existsSync(dest)){const cp=(s,d)=>{fs.mkdirSync(d,{recursive:true});for(const f of fs.readdirSync(s)){const sp=p.join(s,f),dp=p.join(d,f);fs.lstatSync(sp).isDirectory()?cp(sp,dp):fs.copyFileSync(sp,dp)}};cp(src,dest);console.log('Copied templates for packaging')}\"",
+    "postpack": "node -e \"const fs=require('fs');const p=require('path');const d=p.resolve(__dirname,'templates');if(fs.existsSync(d)){fs.rmSync(d,{recursive:true,force:true});console.log('Cleaned up templates after packaging')}\""
   },
   "bin": {
     "titan": "./index.js",
@@ -22,13 +30,12 @@
   },
   "optionalDependencies": {
     "@titanpl/engine-win32-x64": "2.0.4",
-    "@titanpl/engine-linux-x64": "2.0.4",
-    "@titanpl/engine-darwin-arm64": "2.0.4"
+    "@titanpl/engine-linux-x64": "2.0.4"
   },
   "dependencies": {
-    "@titanpl/packet": "2.0.4",
+    "@titanpl/packet": "4.0.2",
     "prompts": "^2.4.2",
     "commander": "^11.0.0",
     "chalk": "^4.1.2"
   }
-}
+}

package/packages/cli/src/commands/build.js

@@ -1,6 +1,7 @@
-import { build } from "@titanpl/packet";
+import { build, release } from "@titanpl/packet";
 
-export async function buildCommand() {
-  const dist = await build(process.cwd());
-  console.log("✔ Build complete →", dist);
+export async function buildCommand(isRelease = false) {
+  const buildFn = isRelease ? release : build;
+  const dist = await buildFn(process.cwd());
+  console.log(`✔ ${isRelease ? 'Release' : 'Build'} complete →`, dist);
 }

package/packages/cli/src/commands/init.js

@@ -164,7 +164,8 @@ export async function initCommand(projectName, templateName) {
     const remapping = {
         "_gitignore": ".gitignore",
         "_dockerignore": ".dockerignore",
-        "_titan.json": "titan.json",
+        "_tanfig.json": "tanfig.json",
+        "_titan.json": "tanfig.json",
         ".env": ".env"
     };
     for (const [srcName, destName] of Object.entries(remapping)) {
@@ -175,6 +176,19 @@ export async function initCommand(projectName, templateName) {
         }
     }
 
+    // 4. Ensure tanfig.json exists with default build config
+    const tanfigPath = path.join(target, "tanfig.json");
+    if (!fs.existsSync(tanfigPath)) {
+        const defaultConfig = {
+            name: projName,
+            build: {
+                files: ["public", "static", "db", "config"]
+            }
+        };
+        fs.writeFileSync(tanfigPath, JSON.stringify(defaultConfig, null, 2));
+    }
+
+
     // Recursive template substitution
     const substitute = (dir) => {
         for (const file of fs.readdirSync(dir)) {

package/packages/cli/src/commands/update.js

@@ -58,9 +58,30 @@ export async function updateCommand() {
         console.log(chalk.yellow(`  ⚠️ Failed to update package.json: ${e.message}`));
     }
 
-    // 2. Refresh Dockerfile and dotfiles from templates
-    const commonDir = path.resolve(__dirname, '..', '..', '..', '..', 'templates', 'common');
-    if (fs.existsSync(commonDir)) {
+    // 2. Migration: rename titan.json to tanfig.json if needed
+    const oldConfigPath = path.join(root, 'titan.json');
+    const newConfigPath = path.join(root, 'tanfig.json');
+    if (fs.existsSync(oldConfigPath) && !fs.existsSync(newConfigPath)) {
+        fs.renameSync(oldConfigPath, newConfigPath);
+        console.log(chalk.green(`  ✔ Migrated titan.json to tanfig.json`));
+    }
+
+    // 3. Refresh Dockerfile and dotfiles from templates
+    let commonDir = null;
+    const tryCommonPaths = [
+        path.resolve(__dirname, '..', '..', '..', '..', 'templates', 'common'), // Monorepo
+        path.resolve(__dirname, '..', '..', 'templates', 'common'), // NPM cli package
+        path.resolve(__dirname, '..', '..', '..', 'templates', 'common') // Fallback
+    ];
+
+    for (const p of tryCommonPaths) {
+        if (fs.existsSync(p)) {
+            commonDir = p;
+            break;
+        }
+    }
+
+    if (commonDir) {
         const filesToSync = [
             ['Dockerfile', 'Dockerfile'],
             ['_dockerignore', '.dockerignore'],

package/packages/cli/src/engine.js

@@ -19,6 +19,7 @@ export function resolveEngineBinaryPath() {
   const arch = os.arch();
   const pkgName = `@titanpl/engine-${platform}-${arch}`;
   const binName = platform === 'win32' ? 'titan-server.exe' : 'titan-server';
+  const shortPkgName = pkgName.split('/').pop();
 
   // 1. Monorepo search (local dev)
   const searchPaths = [
@@ -31,8 +32,14 @@ export function resolveEngineBinaryPath() {
   for (let startPath of searchPaths) {
     let current = startPath;
     for (let i = 0; i < 8; i++) {
-      const potential = path.join(current, 'engine', 'target', 'release', binName);
-      if (fs.existsSync(potential)) return potential;
+      // Check built binary (engine/target/release/...)
+      const builtBin = path.join(current, 'engine', 'target', 'release', binName);
+      if (fs.existsSync(builtBin)) return builtBin;
+
+      // Check package binary (packages/engine-*/bin/...)
+      const pkgBin = path.join(current, 'packages', shortPkgName, 'bin', binName);
+      if (fs.existsSync(pkgBin)) return pkgBin;
+
       const parent = path.dirname(current);
       if (parent === current) break;
       current = parent;
@@ -47,15 +54,38 @@ export function resolveEngineBinaryPath() {
   } catch (e) { }
 
   // 3. Fallback: sibling in node_modules (global install layout)
-  const cliParent = path.dirname(path.dirname(__dirname)); // up from cli/src → cli → parent
-  const siblingBin = path.join(cliParent, pkgName, 'bin', binName);
-  if (fs.existsSync(siblingBin)) return siblingBin;
+  // We need to handle scoped packages correctly. 
+  // If we are at .../node_modules/@titanpl/cli/src
+  // Up 1: .../node_modules/@titanpl/cli
+  // Up 2: .../node_modules/@titanpl
+  // Up 3: .../node_modules (This is where the engine package should be)
+  let current = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const potentialNm = path.join(current, 'node_modules');
+    if (fs.existsSync(potentialNm)) {
+      const siblingBin = path.join(potentialNm, pkgName, 'bin', binName);
+      if (fs.existsSync(siblingBin)) return siblingBin;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
 
-  // 4. Walk upwards from current dir searching for node_modules/@titanpl/engine-...
+  // 4. Walk upwards from current dir searching for binary in root or .ext/node_modules
   let searchDir = process.cwd();
   for (let i = 0; i < 5; i++) {
+    // Check root (Directly in build/ folder)
+    const rootBin = path.join(searchDir, binName);
+    if (fs.existsSync(rootBin)) return rootBin;
+
+    // Check node_modules
     const nmBin = path.join(searchDir, 'node_modules', pkgName, 'bin', binName);
     if (fs.existsSync(nmBin)) return nmBin;
+
+    // Check .ext (Release mode layout)
+    const extBin = path.join(searchDir, '.ext', pkgName, 'bin', binName);
+    if (fs.existsSync(extBin)) return extBin;
+
     const parent = path.dirname(searchDir);
     if (parent === searchDir) break;
     searchDir = parent;
@@ -110,7 +140,8 @@ export function startEngine(watchMode = false) {
     env: {
       ...process.env,
       TITAN_ENV: watchMode ? 'development' : 'production',
-      Titan_Dev: watchMode ? '1' : '0'
+      TITAN_DEV: watchMode ? '1' : '0',
+      NODE_ENV: watchMode ? 'development' : 'production'
     }
   });
 

package/packages/packet/index.js

@@ -32,6 +32,25 @@ function ensureDist(root) {
   return dist;
 }
 
+/**
+ * Recursive copy
+ */
+function copyDir(src, dest, filter) {
+  if (filter && !filter(src)) return;
+
+  const stats = fs.lstatSync(src);
+  if (stats.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    for (const file of fs.readdirSync(src)) {
+      copyDir(path.join(src, file), path.join(dest, file), filter);
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
 /**
  * Production build
  */
@@ -51,6 +70,192 @@ export async function build(root = process.cwd()) {
   return dist;
 }
 
+/**
+ * Release build (Production ready folder)
+ */
+export async function release(root = process.cwd()) {
+  const dist = await build(root);
+  const buildDir = path.join(root, "build");
+
+  // Read config
+  let config = {};
+  const configPath = fs.existsSync(path.join(root, "tanfig.json"))
+    ? path.join(root, "tanfig.json")
+    : fs.existsSync(path.join(root, "titan.json"))
+      ? path.join(root, "titan.json")
+      : null;
+
+  if (configPath) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (e) { }
+  }
+
+  const filesToCopy = config.build && config.build.files ? config.build.files : ["public", "static", "db", "config"];
+
+  // Clear or ensure build dir
+  if (fs.existsSync(buildDir)) {
+    fs.rmSync(buildDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(buildDir, { recursive: true });
+
+  // 1. Copy dist
+  copyDir(dist, path.join(buildDir, "dist"));
+
+  // 2. Extra files/folders from root based on config
+  for (const item of filesToCopy) {
+    const src = path.join(root, item);
+    if (fs.existsSync(src)) {
+      const dest = path.join(buildDir, item);
+      copyDir(src, dest);
+    }
+  }
+
+  // 3. Copy package.json
+  const pkgPath = path.join(root, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    fs.copyFileSync(pkgPath, path.join(buildDir, "package.json"));
+  }
+
+  // 4. Create .env
+  fs.writeFileSync(path.join(buildDir, ".env"), "TITAN_DEV=0\n");
+
+  // 5. Extract extensions
+  const extDir = path.join(buildDir, ".ext");
+  fs.mkdirSync(extDir, { recursive: true });
+
+  const nodeModules = path.join(root, "node_modules");
+  if (fs.existsSync(nodeModules)) {
+    const findExtensions = (dir, depth = 0) => {
+      if (depth > 2) return;
+      if (!fs.existsSync(dir)) return;
+
+      const files = fs.readdirSync(dir);
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        try {
+          const stats = fs.lstatSync(fullPath);
+          if (stats.isDirectory()) {
+            if (file === "node_modules" && depth > 0) continue;
+
+            const titanJson = path.join(fullPath, "titan.json");
+            if (fs.existsSync(titanJson)) {
+              let targetPkgName = file;
+              const parentDirName = path.basename(dir);
+              if (parentDirName.startsWith("@")) {
+                targetPkgName = path.join(parentDirName, file);
+              }
+
+              const destPath = path.join(extDir, targetPkgName);
+              fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+              copyDir(fullPath, destPath, (src) => {
+                const rel = path.relative(fullPath, src);
+                return !rel.startsWith("node_modules");
+              });
+            } else {
+              findExtensions(fullPath, depth + 1);
+            }
+          }
+        } catch (e) { }
+      }
+    };
+    findExtensions(nodeModules);
+  }
+
+  // 6. Copy Engine binaries
+  if (fs.existsSync(path.join(nodeModules, "@titanpl"))) {
+    const scopeDir = path.join(nodeModules, "@titanpl");
+    const folders = fs.readdirSync(scopeDir);
+    for (const folder of folders) {
+      if (folder.startsWith("engine-")) {
+        const engineDest = path.join(extDir, "@titanpl", folder);
+        copyDir(path.join(scopeDir, folder), engineDest);
+      }
+    }
+  }
+
+  // 7. Create node_modules junction to .ext for engine resolution
+  // If env is 'deploy' or 'production', we might want to skip this for a cleaner build
+  const buildEnv = config.build && (config.build.env || config.build.purpose) ? (config.build.env || config.build.purpose) : "test";
+
+  if (buildEnv !== "deploy" && buildEnv !== "production") {
+    const nmSymlink = path.join(buildDir, "node_modules");
+    if (!fs.existsSync(nmSymlink)) {
+      try {
+        // Junctions don't require admin on Windows
+        fs.symlinkSync(".ext", nmSymlink, "junction");
+      } catch (e) {
+        try {
+          fs.symlinkSync(".ext", nmSymlink, "dir");
+        } catch (e2) {
+          // Fallback or ignore if symlink creation is totally restricted
+        }
+      }
+    }
+  }
+
+  // 8. Create 'titan' executable link in the build root for easy starting
+  const binName = process.platform === "win32" ? "titan-server.exe" : "titan-server";
+  let engineBin = null;
+
+  // Strategy A: Search in the .ext we just populated
+  const findInExt = (dir) => {
+    if (!fs.existsSync(dir)) return null;
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+      const full = path.join(dir, entry);
+      if (fs.statSync(full).isDirectory()) {
+        // Check both pkgRoot/bin/titan-server and pkgRoot/titan-server (some layouts differ)
+        const p1 = path.join(full, "bin", binName);
+        if (fs.existsSync(p1)) return p1;
+        const p2 = path.join(full, binName);
+        if (fs.existsSync(p2)) return p2;
+
+        const found = findInExt(full);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+
+  engineBin = findInExt(extDir);
+
+  // Strategy B: Monorepo fallback (if building inside the titanpl repo)
+  if (!engineBin) {
+    let current = root;
+    for (let i = 0; i < 5; i++) {
+      const potential = path.join(current, "engine", "target", "release", binName);
+      if (fs.existsSync(potential)) {
+        engineBin = potential;
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+
+  if (engineBin) {
+    const linkName = binName; // Keep the original name 'titan-server'
+    const linkPath = path.join(buildDir, linkName);
+
+    if (!fs.existsSync(linkPath)) {
+      try {
+        // Always copy the binary to the root for maximum portability in the 'build' folder
+        fs.copyFileSync(engineBin, linkPath);
+        if (process.platform !== "win32") {
+          fs.chmodSync(linkPath, 0o755);
+        }
+      } catch (e) {
+        console.error(`[Titan] Failed to create titan binary: ${e.message}`);
+      }
+    }
+  }
+
+  return buildDir;
+}
+
 /**
  * Dev mode build
  */

package/packages/packet/js/titan/bundle.js

@@ -33,20 +33,32 @@ const NODE_BUILTIN_MAP = {
   "node:util": "@titanpl/node/util",
 };
 
-const titanNodeCompatPlugin = {
-  name: "titan-node-compat",
-  setup(build) {
-    build.onResolve({ filter: /.*/ }, args => {
-      if (NODE_BUILTIN_MAP[args.path]) {
-        try {
-          const resolved = require.resolve(NODE_BUILTIN_MAP[args.path]);
-          return { path: resolved };
-        } catch (e) {
-          throw new Error(`[TitanPL] Failed to resolve Node shim: ${NODE_BUILTIN_MAP[args.path]}`);
+const createTitanNodeCompatPlugin = (root) => {
+  const rootRequire = createRequire(path.join(root, 'package.json'));
+
+  return {
+    name: "titan-node-compat",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, args => {
+        if (NODE_BUILTIN_MAP[args.path]) {
+          const shimPkg = NODE_BUILTIN_MAP[args.path];
+          try {
+            // 1. Try to resolve from project root (local node_modules)
+            const resolved = rootRequire.resolve(shimPkg);
+            return { path: resolved };
+          } catch (e) {
+            try {
+              // 2. Fallback to CLI's own context
+              const resolved = require.resolve(shimPkg);
+              return { path: resolved };
+            } catch (e2) {
+              throw new Error(`[TitanPL] Failed to resolve Node shim: ${shimPkg}. Ensure @titanpl/node is installed.`);
+            }
+          }
         }
-      }
-    });
-  }
+      });
+    }
+  };
 };
 
 function getTitanVersion() {
@@ -96,7 +108,7 @@ export async function bundleFile(options) {
       platform: 'node',
       target,
       logLevel: 'silent',
-      plugins: [titanNodeCompatPlugin],
+      plugins: [createTitanNodeCompatPlugin(options.root || process.cwd())],
       banner: { js: "var Titan = t;" },
       footer: options.footer || {}
     });
@@ -135,6 +147,7 @@ export async function bundle(options = {}) {
 
     try {
       await bundleFile({
+        root,
         entryPoint,
         outfile,
         footer: {

package/packages/packet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/packet",
-  "version": "2.0.4",
+  "version": "4.0.2",
   "description": "The bundler for TitanPl servers.",
   "keywords": [
     "bundler",

package/packages/packet/ts/titan/bundle.js

@@ -34,20 +34,32 @@ const NODE_BUILTIN_MAP = {
     "node:util": "@titanpl/node/util",
 };
 
-const titanNodeCompatPlugin = {
-    name: "titan-node-compat",
-    setup(build) {
-        build.onResolve({ filter: /.*/ }, args => {
-            if (NODE_BUILTIN_MAP[args.path]) {
-                try {
-                    const resolved = require.resolve(NODE_BUILTIN_MAP[args.path]);
-                    return { path: resolved };
-                } catch (e) {
-                    throw new Error(`[TitanPL] Failed to resolve Node shim: ${NODE_BUILTIN_MAP[args.path]}`);
+const createTitanNodeCompatPlugin = (root) => {
+    const rootRequire = createRequire(path.join(root, 'package.json'));
+
+    return {
+        name: "titan-node-compat",
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, args => {
+                if (NODE_BUILTIN_MAP[args.path]) {
+                    const shimPkg = NODE_BUILTIN_MAP[args.path];
+                    try {
+                        // 1. Try to resolve from project root (local node_modules)
+                        const resolved = rootRequire.resolve(shimPkg);
+                        return { path: resolved };
+                    } catch (e) {
+                        try {
+                            // 2. Fallback to CLI's own context
+                            const resolved = require.resolve(shimPkg);
+                            return { path: resolved };
+                        } catch (e2) {
+                            throw new Error(`[TitanPL] Failed to resolve Node shim: ${shimPkg}. Ensure @titanpl/node is installed.`);
+                        }
+                    }
                 }
-            }
-        });
-    }
+            });
+        }
+    };
 };
 
 function getTitanVersion() {
@@ -140,7 +152,7 @@ export async function bundleFile(options) {
             platform: 'node',
             target,
             logLevel: 'silent',
-            plugins: [titanNodeCompatPlugin],
+            plugins: [createTitanNodeCompatPlugin(options.root || process.cwd())],
             banner: { js: "var Titan = t;" },
             footer: options.footer || {}
         });
@@ -198,6 +210,7 @@ export async function bundle(options = {}) {
 
         try {
             await bundleFile({
+                root,
                 entryPoint,
                 outfile,
                 footer: {

package/templates/common/Dockerfile

@@ -14,31 +14,14 @@ ENV NODE_ENV=production
 
 COPY package.json package-lock.json* ./
 
-# Install with optional dependencies so it grabs the correct engine for the Linux builder
+# Install dependencies (including optional engines)
 RUN npm install --include=optional
 
-# ------------------------------------------------
-# Extract Titan Extensions (packages with titan.json)
-# ------------------------------------------------
-RUN mkdir -p /app/.ext && \
-    find node_modules -mindepth 2 -maxdepth 3 -type f -name "titan.json" | while read file; do \
-    pkg_dir=$(dirname "$file"); \
-    pkg_name=$(basename "$pkg_dir"); \
-    echo "Extracting Titan extension: $pkg_name"; \
-    cp -a "$pkg_dir" "/app/.ext/$pkg_name"; \
-    rm -rf "/app/.ext/$pkg_name/node_modules"; \
-    done
-
-# ------------------------------------------------
-# Copy ANY installed Titan Engine (Architecture agnostic)
-# ------------------------------------------------
-RUN mkdir -p /app/.ext/@titanpl && \
-    cp -r node_modules/@titanpl/engine-linux-* /app/.ext/@titanpl/
-
 COPY . .
 
-# Run the Titan build step
-RUN npx titan build
+# Run the Titan release build step
+# This extracts extensions to .ext and prepares the 'build/' folder
+RUN npx titan build --release
 
 
 # ================================================================
@@ -55,31 +38,11 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates curl \
     && rm -rf /var/lib/apt/lists/*
 
-# copy dist contents into /app/dist
-COPY --from=builder /app/dist/ ./dist/
-
-# titan extensions + engine
-COPY --from=builder /app/.ext ./.ext
-
-# runtime assets
-COPY --from=builder /app/package.json ./package.json
-
-# ---------------- 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
+# Copy the entire release build folder prepared by Stage 1
+COPY --from=builder /app/build ./
 
-# CRITICAL SYSTEM SETUP:
-# 1. Mandatory .env file (Engine requires it for config parsing)
-# 2. Node modules symlink for extension JS dependency resolution
-RUN echo "TITAN_DEV=0" > .env && \
-    ln -s /app/.ext /app/node_modules && \
-    chown -R titan:titan /app
+# Ensure permissions
+RUN chown -R titan:titan /app
 
 # Standard environment variables
 ENV HOST=0.0.0.0
@@ -89,10 +52,9 @@ ENV TITAN_DEV=0
 USER titan
 EXPOSE 5100
 
-# Health check to ensure the server is alive
+# Health check
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:5100/ || exit 1
 
-# DYNAMIC ENTRYPOINT: Finds the correct architecture binary and starts it
-# This allows the SAME image to work on x64 vs ARM64 servers.
-CMD ["/bin/sh", "-c", "exec $(find .ext/@titanpl/engine-linux-* -name titan-server -type f | head -n 1) run dist"]
+# Start the server using the 'titan-server' binary created by the release process
+CMD ["./titan-server", "run", "dist"]

package/templates/common/README.md

@@ -0,0 +1,85 @@
+# ⏣ Titan Project
+
+Welcome to your new **Titan Planet** project! Titan is a high-performance web framework designed for scale, speed, and developer happiness.
+
+## 🚀 Getting Started
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Start Development Server
+Run the project in development mode with hot-reloading:
+```bash
+titan dev
+```
+
+### 3. Build for Production
+Create a self-contained production bundle in the `build/` directory:
+```bash
+titan build --release
+```
+
+### 4. Run Production Server
+```bash
+cd build
+titan start
+```
+
+---
+
+## 📂 Project Structure
+
+- `app/actions/` - Your JavaScript/TypeScript backend logic.
+- `public/` - Static assets served directly (images, robots.txt, etc.).
+- `tanfig.json` - Core project configuration and build settings.
+- `.env` - Environment variables.
+
+---
+
+## 🛠 Configuration (`tanfig.json`)
+
+Your project uses `tanfig.json` to control the build and runtime behavior.
+
+```json
+{
+  "name": "my-titan-app",
+  "build": {
+    "purpose": "test",
+    "files": ["public", "static", "db", "config"]
+  }
+}
+```
+
+### Build Options:
+- **`purpose`**: 
+  - `test`: (Default) Creates a `node_modules` junction for local testing.
+  - `deploy`: Slim build without `node_modules`, ready for production.
+- **`files`**: List of folders/files from the root to include in the production `build/` folder.
+
+---
+
+## 🐳 Docker Deployment
+
+This project comes with a pre-configured, multi-stage `Dockerfile` optimized for Titan's native engine.
+
+### Build Image
+```bash
+docker build -t my-titan-app .
+```
+
+### Run Container
+```bash
+docker run -p 5100:5100 my-titan-app
+```
+
+---
+
+## 🌐 Community & Support
+
+- **Documentation**: [docs.titanpl.com](https://titanpl.vercel.app)
+- **GitHub**: [github.com/t8nlab/titanpl](https://github.com/t8nlab/titanpl)
+- **Discord**: [Join our community](https://discord.gg/titanpl)
+
+Built with ❤️ by the **Titan Planet** team.

package/templates/common/_gitignore

@@ -11,6 +11,7 @@ dist/
 .titan/
 .ext/
 .env
+build/
 
 # Rust Build Artifacts (If using Hybrid)
 server/target/

package/templates/common/_tanfig.json

@@ -0,0 +1,14 @@
+{
+    "name": "{{name}}",
+    "description": "A powerful Titan Planet project",
+    "version": "1.0.0",
+    "build": {
+        "purpose": "test",
+        "files": [
+            "public",
+            "static",
+            "db",
+            "config"
+        ]
+    }
+}

package/templates/js/package.json

@@ -13,6 +13,10 @@
     "@titanpl/node": "latest",
     "@titanpl/packet": "2.0.4"
   },
+  "optionalDependencies": {
+    "@titanpl/engine-linux-x64": "2.0.5",
+    "@titanpl/engine-win32-x64": "2.0.3"
+  },
   "scripts": {
     "build": "titan build",
     "dev": "titan dev",
@@ -25,4 +29,4 @@
     "eslint-plugin-titanpl": "latest"
   },
   "version": "2.0.4"
-}
+}

package/templates/ts/package.json

@@ -14,6 +14,11 @@
     "@titanpl/packet": "2.0.4",
     "typescript": "^5.0.0"
   },
+  "optionalDependencies": {
+    "@titanpl/engine-linux-arm64": "2.0.5",
+    "@titanpl/engine-linux-x64": "2.0.5",
+    "@titanpl/engine-win32-x64": "2.0.3"
+  },
   "scripts": {
     "build": "titan build",
     "dev": "titan dev",
@@ -27,4 +32,4 @@
     "@typescript-eslint/parser": "^8.54.0"
   },
   "version": "2.0.4"
-}
+}