@titanpl/cli 4.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": "4.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",

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