@titanpl/cli 3.0.0 → 5.0.0

package/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titanpl/cli",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "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,8 +30,7 @@
   },
   "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",
@@ -31,4 +38,4 @@
     "commander": "^11.0.0",
     "chalk": "^4.1.2"
   }
-}
+}

package/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/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/src/engine.js

@@ -51,11 +51,21 @@ export function resolveEngineBinaryPath() {
   const siblingBin = path.join(cliParent, pkgName, 'bin', binName);
   if (fs.existsSync(siblingBin)) return siblingBin;
 
-  // 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 +120,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/templates/common/.env

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

package/templates/common/Dockerfile

@@ -0,0 +1,60 @@
+# ================================================================
+# STAGE 1 — Builder
+# ================================================================
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# build-essential is required for native Titan extensions (C++ or Rust based)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential pkg-config git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV NODE_ENV=production
+
+COPY package.json package-lock.json* ./
+
+# Install dependencies (including optional engines)
+RUN npm install --include=optional
+
+COPY . .
+
+# Run the Titan release build step
+# This extracts extensions to .ext and prepares the 'build/' folder
+RUN npx titan build --release
+
+
+# ================================================================
+# STAGE 2 — Runtime (Optimized Pure Engine)
+# ================================================================
+FROM ubuntu:24.04
+
+# Use an unprivileged user for security
+RUN groupadd -r titan && useradd -r -g titan titan
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy the entire release build folder prepared by Stage 1
+COPY --from=builder /app/build ./
+
+# Ensure permissions
+RUN chown -R titan:titan /app
+
+# Standard environment variables
+ENV HOST=0.0.0.0
+ENV PORT=5100
+ENV TITAN_DEV=0
+
+USER titan
+EXPOSE 5100
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:5100/ || exit 1
+
+# 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://docs.titanpl.com)
+- **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/_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,34 @@
+# Node & Packages
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json
+yarn.lock
+
+# Titan Engine (Auto-generated - DO NOT COMMIT)
+dist/
+.titan/
+.ext/
+.env
+build/
+
+# 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

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