@titanpl/cli 1.0.0 → 1.4.0

package/README.md

@@ -0,0 +1,17 @@
+# @titanpl/cli
+
+The command-line interface (CLI) for Titan Planet. It provides the `titan` and `tit` commands for initializing, building, and running Titan Planet servers.
+
+## 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.
+
+## 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
+```
+
+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.

package/index.js

@@ -8,6 +8,7 @@ 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 { updateCommand } from "./src/commands/update.js";
 import { initCommand } from "./src/commands/init.js";
 
 /* -------------------------------------------------------
@@ -51,9 +52,11 @@ ${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("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")}
     ${cyan("migrate")}   ${gray("Migrate a legacy project to the new architecture")}
 
   ${bold("Options:")}
@@ -68,6 +71,7 @@ ${gray("  The Titan Planet Engine runs your JS/TS server natively without Node.j
 /* -------------------------------------------------------
  * CLI Router
  * ----------------------------------------------------- */
+process.title = "TitanPL";
 const cmd = process.argv[2];
 
 (async () => {
@@ -105,6 +109,18 @@ const cmd = process.argv[2];
         break;
       }
 
+      case "create": {
+        const type = process.argv[3];
+        const name = process.argv[4];
+        if (type === "ext" || type === "extension") {
+          await initCommand(name, "extension");
+        } else {
+          // Fallback to init behavior
+          await initCommand(type, null);
+        }
+        break;
+      }
+
       case "build":
         console.log(cyan("→ Building Titan project..."));
         await buildCommand();
@@ -120,6 +136,10 @@ const cmd = process.argv[2];
         startCommand();
         break;
 
+      case "update":
+        await updateCommand();
+        break;
+
       case "migrate":
         await migrateCommand();
         break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@titanpl/cli",
-  "version": "1.0.0",
-  "description": "The gravity and other builtins binary of TitanPl",
+  "version": "1.4.0",
+  "description": "The unified CLI for Titan Planet. Use it to create, manage, build, and deploy high-performance backend projects.",
   "keywords": [
     "titanpl",
     "titan",
@@ -16,17 +16,19 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "bin": {
-    "titan": "./index.js"
+    "titan": "./index.js",
+    "titanpl": "./index.js",
+    "tit": "./index.js"
   },
   "optionalDependencies": {
-    "@titanpl/engine-win32-x64": "26.16.0",
-    "@titanpl/engine-linux-x64": "26.16.0",
-    "@titanpl/engine-darwin-arm64": "26.16.0"
+    "@titanpl/engine-win32-x64": "1.4.0",
+    "@titanpl/engine-linux-x64": "1.4.0",
+    "@titanpl/engine-darwin-arm64": "1.4.0"
   },
   "dependencies": {
-    "@titanpl/packet": "26.16.0",
+    "@titanpl/packet": "1.4.0",
     "prompts": "^2.4.2",
     "commander": "^11.0.0",
     "chalk": "^4.1.2"
   }
-}
+}

package/src/commands/dev.js

@@ -1,7 +1,5 @@
-import { startEngine } from "../engine.js";
+import { dev } from "@titanpl/packet";
 
 export async function devCommand() {
-  // The Titan Engine now handles all compilation, watch, and routing natively.
-  // There is no need for JS-based watchers or Node.js process managers.
-  startEngine(true);
+  await dev(process.cwd());
 }

package/src/commands/init.js

@@ -112,25 +112,58 @@ export async function initCommand(projectName, templateName) {
     console.log(chalk.cyan(`\n→ Creating new Titan project in '${projName}'...\n`));
 
     // 1. Copy common
-    copyDir(commonDir, target, ["_gitignore", "_dockerignore"]);
+    copyDir(commonDir, target);
 
     // 2. Copy specific template
-    copyDir(templateDir, target, ["_gitignore", "_dockerignore"]);
+    copyDir(templateDir, target);
 
-    // 3. Dotfiles
-    const dotfiles = {
+    // 3. Dotfiles and Template Remapping
+    const remapping = {
         "_gitignore": ".gitignore",
         "_dockerignore": ".dockerignore",
+        "_titan.json": "titan.json",
         ".env": ".env"
     };
-    for (const [srcName, destName] of Object.entries(dotfiles)) {
-        const src = path.join(commonDir, srcName);
+    for (const [srcName, destName] of Object.entries(remapping)) {
+        const src = path.join(target, srcName);
         const dest = path.join(target, destName);
         if (fs.existsSync(src)) {
-            fs.copyFileSync(src, dest);
+            fs.renameSync(src, dest);
         }
     }
 
+    // Recursive template substitution
+    const substitute = (dir) => {
+        for (const file of fs.readdirSync(dir)) {
+            const fullPath = path.join(dir, file);
+            if (fs.lstatSync(fullPath).isDirectory()) {
+                if (file !== "node_modules" && file !== ".git" && file !== "target") {
+                    substitute(fullPath);
+                }
+            } else {
+                // Only process text files
+                const ext = path.extname(file).toLowerCase();
+                const textExts = ['.js', '.ts', '.json', '.md', '.txt', '.rs', '.toml', '.html', '.css', '.d.ts'];
+                if (textExts.includes(ext) || file === ".env" || file === "Dockerfile") {
+                    let content = fs.readFileSync(fullPath, 'utf8');
+                    let changed = false;
+                    if (content.includes("{{name}}")) {
+                        content = content.replace(/{{name}}/g, projName);
+                        changed = true;
+                    }
+                    if (content.includes("{{native_name}}")) {
+                        content = content.replace(/{{native_name}}/g, projName.replace(/-/g, '_'));
+                        changed = true;
+                    }
+                    if (changed) {
+                        fs.writeFileSync(fullPath, content);
+                    }
+                }
+            }
+        }
+    };
+    substitute(target);
+
     console.log(chalk.gray(`  Installing dependencies...`));
 
     await new Promise((resolve, reject) => {

package/src/commands/migrate.js

@@ -70,6 +70,36 @@ export async function migrateCommand() {
         }
     }
 
+    // 4. Synchronize Dockerfile and other common files
+    try {
+        const commonDir = path.resolve(__dirname, '..', '..', '..', '..', 'templates', 'common');
+        if (fs.existsSync(commonDir)) {
+            const filesToSync = [
+                ['Dockerfile', 'Dockerfile'],
+                ['_dockerignore', '.dockerignore'],
+                ['_gitignore', '.gitignore'],
+                ['app/t.native.d.ts', 'app/t.native.d.ts'],
+                ['app/t.native.js', 'app/t.native.js']
+            ];
+
+            for (const [srcRel, destRel] of filesToSync) {
+                const src = path.join(commonDir, srcRel);
+                const dest = path.join(root, destRel);
+                if (fs.existsSync(src)) {
+                    // Create parent dir if needed
+                    const parent = path.dirname(dest);
+                    if (!fs.existsSync(parent)) {
+                        fs.mkdirSync(parent, { recursive: true });
+                    }
+                    fs.copyFileSync(src, dest);
+                }
+            }
+            console.log(`   Synchronized Dockerfiles and native definitions.`);
+        }
+    } catch (e) {
+        console.log(`   ⚠️ Failed to synchronize common template files.`);
+    }
+
     console.log(`\n🎉 Migration complete!`);
     console.log(`   Please run 'npm install' to fetch the new dependencies.`);
     console.log(`   Then run 'titan dev' to start your application.\n`);

package/src/commands/update.js

@@ -0,0 +1,90 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function updateCommand() {
+    const root = process.cwd();
+    console.log(chalk.cyan(`\n→ Updating Titan project to latest...`));
+
+    const pkgPath = path.join(root, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        console.log(chalk.red(`✖ No package.json found. Are you in a project root ? `));
+        return;
+    }
+
+    // 1. Update package.json versions
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        let modified = false;
+
+        const titanDeps = [
+            'titanpl',
+            'titanpl-sdk',
+            '@titanpl/cli',
+            '@titanpl/route',
+            '@titanpl/native',
+            '@titanpl/packet',
+            '@titanpl/core',
+            '@titanpl/node'
+        ];
+
+        if (pkg.dependencies) {
+            for (const dep of titanDeps) {
+                if (pkg.dependencies[dep]) {
+                    pkg.dependencies[dep] = "latest";
+                    modified = true;
+                }
+            }
+        }
+
+        if (pkg.devDependencies) {
+            for (const dep of titanDeps) {
+                if (pkg.devDependencies[dep]) {
+                    pkg.devDependencies[dep] = "latest";
+                    modified = true;
+                }
+            }
+        }
+
+        if (modified) {
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+            console.log(chalk.green(`  ✔ Updated Titan dependencies in package.json`));
+        }
+    } catch (e) {
+        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)) {
+        const filesToSync = [
+            ['Dockerfile', 'Dockerfile'],
+            ['_dockerignore', '.dockerignore'],
+            ['_gitignore', '.gitignore'],
+        ];
+
+        for (const [srcName, destName] of filesToSync) {
+            const src = path.join(commonDir, srcName);
+            const dest = path.join(root, destName);
+            if (fs.existsSync(src)) {
+                fs.copyFileSync(src, dest);
+                console.log(chalk.green(`  ✔ Synchronized ${destName}`));
+            }
+        }
+
+        // Also update app/t.native.d.ts if it exists
+        const nativeTypesSrc = path.join(commonDir, 'app', 't.native.d.ts');
+        const nativeTypesDest = path.join(root, 'app', 't.native.d.ts');
+        if (fs.existsSync(nativeTypesSrc) && fs.existsSync(path.join(root, 'app'))) {
+            fs.copyFileSync(nativeTypesSrc, nativeTypesDest);
+            console.log(chalk.green(`  ✔ Updated app/t.native.d.ts`));
+        }
+    }
+
+    console.log(chalk.green(`\n✔ Update complete!\n`));
+    console.log(chalk.yellow(`  Please run 'npm install' to apply changes.\n`));
+}

package/src/engine.js

@@ -16,16 +16,38 @@ export function getEngineBinaryPath() {
   const pkgName = `@titanpl/engine-${platform}-${arch}`;
   const binName = platform === 'win32' ? 'titan-server.exe' : 'titan-server';
 
-  // 1. Monorepo Dev Fallback
-  const serverExeName = platform === 'win32' ? 'titan-server.exe' : 'titan-server';
-  const localFallback = path.resolve(__dirname, '..', '..', '..', 'engine', 'target', 'release', serverExeName);
-  if (fs.existsSync(localFallback)) {
-    return localFallback;
+  // 1. Robust Binary Discovery (Monorepo, Local, or Global)
+  const searchPaths = [
+    __dirname,
+    process.cwd(),
+    path.join(process.cwd(), '..'),
+    path.join(process.cwd(), '..', '..')
+  ];
+
+  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;
+
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
   }
 
   // 2. Resolve installed optional dependency
   try {
-    const pkgPath = require.resolve(`${pkgName}/package.json`);
+    // We use a try/catch specifically for the resolve to provide a better diagnostic
+    let pkgPath;
+    try {
+      pkgPath = require.resolve(`${pkgName}/package.json`);
+    } catch (e) {
+      // Fallback: check if the binary exists in a standard location even if require.resolve fails
+      const fallbackBin = path.join(process.cwd(), 'node_modules', pkgName, 'bin', binName);
+      if (fs.existsSync(fallbackBin)) return fallbackBin;
+      throw e;
+    }
     const pkgDir = path.dirname(pkgPath);
     const binaryPath = path.join(pkgDir, 'bin', binName);
 
@@ -58,7 +80,7 @@ export function startEngine(watchMode = false) {
   console.log(`🚀 Starting Titan Engine...`);
 
   const engineProcess = spawn(binaryPath, args, {
-    stdio: 'inherit',
+    stdio: ['inherit', 'pipe', 'pipe'],
     env: {
       ...process.env,
       TITAN_ENV: watchMode ? 'development' : 'production',
@@ -66,9 +88,54 @@ export function startEngine(watchMode = false) {
     }
   });
 
+  let stderrBuffer = "";
+
+  engineProcess.stdout.pipe(process.stdout);
+  engineProcess.stderr.on('data', (data) => {
+    const chunk = data.toString();
+    stderrBuffer += chunk;
+    process.stderr.write(data);
+  });
+
   engineProcess.on('close', (code) => {
-    if (code !== 0 && code !== null && !engineProcess._isKilling) {
-      console.error(`\n❌ [Titan Engine died with exit code ${code}]`);
+    if (code !== 0 && code !== null) {
+      // Check for port binding errors
+      const isPortError = stderrBuffer.includes("Address already in use") ||
+        stderrBuffer.includes("address in use") ||
+        stderrBuffer.includes("os error 10048") || // Windows
+        stderrBuffer.includes("EADDRINUSE") ||
+        stderrBuffer.includes("AddrInUse");
+
+      if (isPortError) {
+        // Try to read intended port
+        let port = 5100;
+        try {
+          const routesPath = path.join(process.cwd(), "dist", "routes.json");
+          if (fs.existsSync(routesPath)) {
+            const routesConfig = JSON.parse(fs.readFileSync(routesPath, "utf8"));
+            if (routesConfig && routesConfig.__config && routesConfig.__config.port) {
+              port = routesConfig.__config.port;
+            }
+          }
+        } catch (e) { }
+
+        const cyan = (t) => `\x1b[36m${t}\x1b[0m`;
+        const yellow = (t) => `\x1b[33m${t}\x1b[0m`;
+        const red = (t) => `\x1b[31m${t}\x1b[0m`;
+
+        console.log("");
+        console.log(red("⏣  Your application cannot enter this orbit"));
+        console.log(red(`↳  Another application is already bound to port ${port}.`));
+        console.log("");
+
+        console.log(yellow("Recommended Actions:"));
+        console.log(yellow("  1.") + " Release the occupied orbit (stop the other service).");
+        console.log(yellow("  2.") + " Assign your application to a new orbit in " + cyan("app/app.js"));
+        console.log(yellow("     Example: ") + cyan(`t.start(${port + 1}, "Titan Running!")`));
+        console.log("");
+      } else {
+        console.error(`\n❌ [Titan Engine died with exit code ${code}]`);
+      }
     }
   });