@nitronjs/framework 0.1.23 → 0.2.0

package/lib/Console/Stubs/page-hydration.tsx

@@ -1,11 +1,12 @@
 import React from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot } from "react-dom/client";
 
 // __COMPONENT_IMPORTS__
 
 declare global {
     interface Window {
         __NITRON_PROPS__?: Record<string, any>;
+        __NITRON_ROOTS__?: Map<HTMLElement, any>;
     }
 }
 
@@ -13,8 +14,9 @@ const componentManifest: Record<string, React.ComponentType<any>> = {};
 
 // __COMPONENT_MANIFEST__
 
-function hydrate() {
+function mount() {
     const props = window.__NITRON_PROPS__ || {};
+    if (!window.__NITRON_ROOTS__) window.__NITRON_ROOTS__ = new Map();
 
     const islands = document.querySelectorAll<HTMLElement>("[data-cid]");
 
@@ -22,24 +24,20 @@ function hydrate() {
         const componentName = element.dataset.island;
         const componentId = element.dataset.cid;
 
-        if (!componentName || !componentId) {
-            return;
-        }
+        if (!componentName || !componentId) return;
 
         const Component = componentManifest[componentName];
-
-        if (!Component) {
-            return;
-        }
+        if (!Component) return;
 
         const componentProps = props[componentId] || {};
 
         try {
-            hydrateRoot(
-                element,
-                React.createElement(Component, componentProps),
-                { identifierPrefix: componentId }
-            );
+            let root = window.__NITRON_ROOTS__.get(element);
+            if (!root) {
+                root = createRoot(element);
+                window.__NITRON_ROOTS__.set(element, root);
+            }
+            root.render(React.createElement(Component, componentProps));
         } catch {
         }
     });
@@ -48,7 +46,8 @@ function hydrate() {
 }
 
 if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", hydrate);
+    document.addEventListener("DOMContentLoaded", mount);
 } else {
-    hydrate();
+    mount();
 }
+

package/lib/Console/Stubs/vendor-dev.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import * as ReactDOMClient from 'react-dom/client';
+import * as ReactJSXRuntime from 'react/jsx-runtime';
+import RefreshRuntime from 'react-refresh/runtime';
+
+Object.assign(window, {
+    __NITRON_REACT__: React,
+    __NITRON_REACT_DOM__: ReactDOM,
+    __NITRON_REACT_DOM_CLIENT__: ReactDOMClient,
+    __NITRON_JSX_RUNTIME__: ReactJSXRuntime
+});
+
+RefreshRuntime.injectIntoGlobalHook(window);
+
+interface RefreshModule {
+    performReactRefresh: () => void;
+    register: (type: any, id: string) => void;
+    createSignatureFunctionForTransform: () => (type: any, key: string, forceReset?: boolean, getCustomHooks?: () => any[]) => any;
+    isLikelyComponentType: (type: any) => boolean;
+}
+
+const NitronRefresh: RefreshModule = {
+    performReactRefresh: () => {
+        if ((RefreshRuntime as any).hasUnrecoverableErrors?.()) {
+            window.location.reload();
+            return;
+        }
+        RefreshRuntime.performReactRefresh();
+    },
+    register: (type: any, id: string) => {
+        RefreshRuntime.register(type, id);
+    },
+    createSignatureFunctionForTransform: () => {
+        return RefreshRuntime.createSignatureFunctionForTransform();
+    },
+    isLikelyComponentType: (type: any) => {
+        return RefreshRuntime.isLikelyComponentType(type);
+    }
+};
+
+(window as any).__NITRON_REFRESH__ = NitronRefresh;
+
+(window as any).$RefreshReg$ = (type: any, id: string) => {
+    RefreshRuntime.register(type, id);
+};
+
+(window as any).$RefreshSig$ = () => {
+    return RefreshRuntime.createSignatureFunctionForTransform();
+};

package/lib/Core/Environment.js

@@ -1,8 +1,36 @@
 import fs from "node:fs";
 
+/**
+ * Environment Manager
+ * 
+ * Handles environment detection and .env file operations.
+ * Development mode is detected automatically based on how the app was started.
+ */
 class Environment {
+    static #isDev = false;
 
-    static update (key, value) {
+    /**
+     * Set development mode (called by DevCommand/BuildCommand)
+     */
+    static setDev(value) {
+        this.#isDev = value;
+    }
+
+    /**
+     * Check if running in development mode
+     */
+    static get isDev() {
+        return this.#isDev;
+    }
+
+    /**
+     * Check if running in production mode
+     */
+    static get isProd() {
+        return !this.#isDev;
+    }
+
+    static update(key, value) {
         let content = fs.readFileSync(".env", 'utf-8');
         const regex = new RegExp(`^${key}=.*`, 'm');
 
@@ -15,7 +43,6 @@ class Environment {
 
         fs.writeFileSync(".env", content.trim() + '\n');
     }
-
 }
 
 export default Environment;

package/lib/Core/Paths.js

@@ -132,20 +132,28 @@ class Paths {
         return path.join(this.#project, "storage/app/public/js");
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // Build Output (.nitron - single hidden folder for all framework artifacts)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    static get nitron() {
+        return path.join(this.#project, ".nitron");
+    }
+
     static get build() {
-        return path.join(this.#project, "build");
+        return path.join(this.#project, ".nitron/build");
     }
 
     static get buildViews() {
-        return path.join(this.#project, "build/views");
+        return path.join(this.#project, ".nitron/build/views");
     }
 
     static get buildFrameworkViews() {
-        return path.join(this.#project, "build/framework/views");
+        return path.join(this.#project, ".nitron/build/framework/views");
     }
 
     static get nitronTemp() {
-        return path.join(this.#project, ".nitron");
+        return path.join(this.#project, ".nitron/temp");
     }
 
     static get jsxRuntime() {

package/lib/Database/Drivers/MySQLDriver.js

@@ -1,4 +1,5 @@
 import mysql from 'mysql2/promise';
+import Environment from '../../Core/Environment.js';
 
 class MySQLDriver {
     #pool = null;
@@ -35,7 +36,7 @@ class MySQLDriver {
     }
 
     async query(sql, bindings = []) {
-        const isProduction = process.env.APP_DEV === 'false';
+        const isProduction = Environment.isProd;
 
         try {
             const connection = await this.#pool.getConnection();
@@ -73,7 +74,7 @@ class MySQLDriver {
     }
 
     async raw(sql) {
-        const isProduction = process.env.APP_DEV === 'false';
+        const isProduction = Environment.isProd;
         
         try {
             const [rows, fields] = await this.#pool.query(sql);
@@ -101,7 +102,7 @@ class MySQLDriver {
     }
 
     #maskSensitiveData(bindings) {
-        if (process.env.APP_DEV === 'true') {
+        if (Environment.isDev) {
             return bindings; // Show all in development
         }
 
@@ -161,7 +162,7 @@ class MySQLDriver {
         }
 
         catch (error) {
-            const isProduction = process.env.APP_DEV === 'false';
+            const isProduction = Environment.isProd;
 
             if (isProduction) {
                 console.error('[MySQLDriver] Transaction query failed', {

package/lib/Database/QueryBuilder.js

@@ -1,4 +1,5 @@
 import { validateDirection, validateIdentifier, validateWhereOperator } from "./QueryValidation.js";
+import Environment from "../Core/Environment.js";
 
 class QueryBuilder {
     #table = null;
@@ -104,9 +105,7 @@ class QueryBuilder {
     }
 
     #sanitizeError(error) {
-        const isProduction = process.env.APP_DEV === 'false';
-
-        if (isProduction) {
+        if (Environment.isProd) {
             console.error('[QueryBuilder] Database error:', {
                 message: error.message,
                 code: error.code,

package/lib/Filesystem/Manager.js

@@ -6,21 +6,39 @@ class FilesystemManager {
     static #publicRoot = Paths.storagePublic;
     static #privateRoot = Paths.storagePrivate;
 
+    /**
+     * Validate path to prevent directory traversal attacks
+     * @throws Error if path escapes base directory
+     */
+    static #validatePath(base, filePath) {
+        const normalizedBase = path.normalize(base) + path.sep;
+        const fullPath = path.normalize(path.join(base, filePath));
+        
+        if (!fullPath.startsWith(normalizedBase)) {
+            throw new Error("Invalid file path: directory traversal detected");
+        }
+        
+        return fullPath;
+    }
+
     static async get(filePath, isPrivate = false) {
         const base = isPrivate ? this.#privateRoot : this.#publicRoot;
-        const fullPath = path.join(base, filePath);
-
+        
         try {
+            const fullPath = this.#validatePath(base, filePath);
             return await fs.promises.readFile(fullPath);
-        } catch {
+        } catch (err) {
+            if (err.message.includes("directory traversal")) throw err;
             return null;
         }
     }
 
     static async put(file, dir, fileName, isPrivate = false) {
         const base = isPrivate ? this.#privateRoot : this.#publicRoot;
-        const folderPath = path.join(base, dir);
-        const fullPath = path.join(folderPath, fileName);
+        
+        // Validate both dir and fileName
+        const folderPath = this.#validatePath(base, dir);
+        const fullPath = this.#validatePath(base, path.join(dir, fileName));
 
         await fs.promises.mkdir(folderPath, { recursive: true });
         await fs.promises.writeFile(fullPath, file._buf);
@@ -30,12 +48,19 @@ class FilesystemManager {
 
     static async delete(filePath, isPrivate = false) {
         const base = isPrivate ? this.#privateRoot : this.#publicRoot;
-        await fs.promises.unlink(path.join(base, filePath));
+        const fullPath = this.#validatePath(base, filePath);
+        await fs.promises.unlink(fullPath);
     }
 
     static exists(filePath, isPrivate = false) {
         const base = isPrivate ? this.#privateRoot : this.#publicRoot;
-        return fs.existsSync(path.join(base, filePath));
+        
+        try {
+            const fullPath = this.#validatePath(base, filePath);
+            return fs.existsSync(fullPath);
+        } catch {
+            return false;
+        }
     }
 
     static url(filePath) {

package/lib/HMR/Server.js

@@ -0,0 +1,87 @@
+import { Server as SocketServer } from "socket.io";
+import path from "path";
+
+class HMRServer {
+    #io = null;
+    #ready = false;
+    #connections = 0;
+
+    setup(httpServer) {
+        if (this.#io) return;
+
+        this.#io = new SocketServer(httpServer, {
+            path: "/__nitron_hmr",
+            transports: ["websocket", "polling"],
+            cors: { origin: "*" },
+            pingTimeout: 60000,
+            pingInterval: 25000,
+            serveClient: true
+        });
+
+        this.#io.on("connection", (socket) => {
+            this.#connections++;
+            socket.on("disconnect", () => { this.#connections--; });
+        });
+
+        this.#ready = true;
+    }
+
+    get isReady() {
+        return this.#ready && this.#io !== null;
+    }
+
+    get connectionCount() {
+        return this.#connections;
+    }
+
+    emitViewUpdate(filePath) {
+        if (!this.#io) return;
+
+        const normalized = filePath.replace(/\\/g, "/");
+        const viewsMatch = normalized.match(/resources\/views\/(.+)\.tsx$/);
+        const viewPath = viewsMatch ? viewsMatch[1].toLowerCase() : path.basename(filePath, ".tsx").toLowerCase();
+
+        this.#io.emit("hmr:update", {
+            type: "view",
+            file: viewPath,
+            url: `/js/${viewPath}.js`,
+            timestamp: Date.now()
+        });
+    }
+
+    emitCss(filePath) {
+        if (!this.#io) return;
+        this.#io.emit("hmr:css", {
+            file: filePath ? path.basename(filePath) : null,
+            timestamp: Date.now()
+        });
+    }
+
+    emitReload(reason) {
+        if (!this.#io) return;
+        this.#io.emit("hmr:reload", {
+            reason,
+            timestamp: Date.now()
+        });
+    }
+
+    emitError(error, filePath) {
+        if (!this.#io) return;
+        this.#io.emit("hmr:error", {
+            file: filePath,
+            message: String(error?.message || error),
+            timestamp: Date.now()
+        });
+    }
+
+    close() {
+        if (this.#io) {
+            this.#io.close();
+            this.#io = null;
+        }
+        this.#ready = false;
+        this.#connections = 0;
+    }
+}
+
+export default new HMRServer();

package/lib/Http/Server.js

@@ -9,6 +9,7 @@ import fastifyHelmet from "@fastify/helmet";
 import fastifyMultipart from "@fastify/multipart";
 import Paths from "../Core/Paths.js";
 import Config from "../Core/Config.js";
+import Environment from "../Core/Environment.js";
 import Route from "../Route/Manager.js";
 import View from "../View/Manager.js";
 import Auth from "../Auth/Manager.js";
@@ -16,8 +17,7 @@ import SessionManager from "../Session/Manager.js";
 import DB from "../Database/DB.js";
 import Log from "../Logging/Manager.js";
 import Loader from "../Route/Loader.js";
-
-const IS_DEV = process.env.APP_DEV === "true";
+import HMRServer from "../HMR/Server.js";
 
 class Server {
     static #server;
@@ -91,7 +91,7 @@ class Server {
             dnsPrefetchControl: { allow: false },
             frameguard: { action: "deny" },
             hidePoweredBy: true,
-            hsts: !IS_DEV,
+            hsts: !Environment.isDev,
             ieNoOpen: true,
             noSniff: true,
             originAgentCluster: true,
@@ -239,13 +239,17 @@ class Server {
             const port = Number(process.env.APP_PORT) || 3000;
             const address = await this.#server.listen({ host, port });
 
+            if (Environment.isDev) {
+                HMRServer.setup(this.#server.server);
+            }
+
             this.#printBanner({ success: true, address, host, port });
 
             Log.info("Server started successfully!", {
                 address,
                 host,
                 port,
-                environment: IS_DEV ? "development" : "production"
+                environment: Environment.isDev ? "development" : "production"
             });
         }
         catch (err) {
@@ -292,7 +296,7 @@ ${color}███╗   ██╗██╗████████╗████
                 `${bold}Address:${reset} ${address}`,
                 `${bold}Host:${reset}    ${host}`,
                 `${bold}Port:${reset}    ${port}`,
-                `${bold}Mode:${reset}    ${IS_DEV ? "development" : "production"}`
+                `${bold}Mode:${reset}    ${Environment.isDev ? "development" : "production"}`
             ]
             : [
                 `${color}${bold}✕${reset} ${bold}Server failed to start${reset}`,

package/lib/Logging/Manager.js

@@ -11,6 +11,14 @@ class LogManager {
         fatal: 4
     };
 
+    static #levelLabels = {
+        debug: "DEBUG",
+        info: "INFO ",
+        warn: "WARN ",
+        error: "ERROR",
+        fatal: "FATAL"
+    };
+
     static debug(message, context = {}) {
         this.#log("debug", message, context);
     }
@@ -48,13 +56,7 @@ class LogManager {
                 return;
             }
 
-            const payload = {
-                level,
-                message,
-                context,
-                timestamp: new Date().toISOString(),
-                pid: process.pid
-            };
+            const timestamp = new Date();
 
             const channel = config.channel;
 
@@ -63,11 +65,11 @@ class LogManager {
             }
 
             if (channel === "console") {
-                this.#logToConsole(payload);
+                this.#logToConsole(level, message, context, timestamp);
             }
 
             if (channel === "file") {
-                this.#logToFile(payload, config);
+                this.#logToFile(level, message, context, timestamp, config);
             }
         } catch (e) {
             console.error("Logger failure:", e.message);
@@ -79,7 +81,18 @@ class LogManager {
         return this.#levels[level] >= this.#levels[configLevel];
     }
 
-    static #logToConsole({ level, message, context, timestamp }) {
+    static #formatTimestamp(date) {
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, "0");
+        const day = String(date.getDate()).padStart(2, "0");
+        const hours = String(date.getHours()).padStart(2, "0");
+        const minutes = String(date.getMinutes()).padStart(2, "0");
+        const seconds = String(date.getSeconds()).padStart(2, "0");
+        const ms = String(date.getMilliseconds()).padStart(3, "0");
+        return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
+    }
+
+    static #logToConsole(level, message, context, timestamp) {
         const colors = {
             debug: "\x1b[90m",
             info: "\x1b[36m",
@@ -102,14 +115,12 @@ class LogManager {
         const bold = "\x1b[1m";
         const dim = "\x1b[2m";
 
-        const date = new Date(timestamp);
-        const time = date.toLocaleTimeString("en-US", { hour12: false });
-        const dateStr = date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+        const time = this.#formatTimestamp(timestamp);
         const width = process.stdout.columns || 80;
 
         console.log(`${color}┌${"─".repeat(width - 2)}${reset}`);
         console.log(`${color}│${reset} ${color}${icon}${reset} ${bold}${level.toUpperCase()}${reset}`);
-        console.log(`${color}│${reset} ${dim}${dateStr} at ${time}${reset}`);
+        console.log(`${color}│${reset} ${dim}${time}${reset}`);
         console.log(`${color}├${"─".repeat(width - 2)}${reset}`);
         console.log(`${color}│${reset}`);
         console.log(`${color}│${reset} ${bold}${message}${reset}`);
@@ -128,7 +139,32 @@ class LogManager {
         console.log();
     }
 
-    static #logToFile(payload, config) {
+    static #formatContext(context, indent = "") {
+        const lines = [];
+        
+        for (const [key, value] of Object.entries(context)) {
+            if (value === null || value === undefined) continue;
+
+            if (typeof value === "object" && !Array.isArray(value)) {
+                lines.push(`${indent}${key}:`);
+                lines.push(...this.#formatContext(value, indent + "  "));
+            }
+            else if (key === "stack" && typeof value === "string") {
+                // Format stack trace nicely
+                lines.push(`${indent}${key}:`);
+                value.split("\n").forEach(line => {
+                    lines.push(`${indent}  ${line.trim()}`);
+                });
+            }
+            else {
+                lines.push(`${indent}${key}: ${value}`);
+            }
+        }
+
+        return lines;
+    }
+
+    static #logToFile(level, message, context, timestamp, config) {
         const filePath = path.resolve(process.cwd(), config.file);
         const dir = path.dirname(filePath);
 
@@ -136,12 +172,26 @@ class LogManager {
             fs.mkdirSync(dir, { recursive: true });
         }
 
-        const logLine = JSON.stringify(payload) + "\n";
+        const time = this.#formatTimestamp(timestamp);
+        const label = this.#levelLabels[level];
+        
+        // Build readable log entry
+        const lines = [];
+        lines.push(`[${time}] [${label}] ${message}`);
+        
+        if (Object.keys(context).length > 0) {
+            const contextLines = this.#formatContext(context, "  ");
+            lines.push(...contextLines);
+        }
+        
+        lines.push(""); // Empty line between entries
+        
+        const logEntry = lines.join("\n") + "\n";
 
         if (config.sync) {
-            fs.appendFileSync(filePath, logLine);
+            fs.appendFileSync(filePath, logEntry);
         } else {
-            fs.appendFile(filePath, logLine, (err) => {
+            fs.appendFile(filePath, logEntry, (err) => {
                 if (err) {
                     console.error("Failed to write log:", err.message);
                 }

package/lib/Route/Loader.js

@@ -1,8 +1,7 @@
 import path from "path";
 import fs from "fs";
 import Paths from "../Core/Paths.js";
-
-const IS_DEV = process.env.APP_DEV === "true";
+import Environment from "../Core/Environment.js";
 
 const DIRECTORIES = [
     Paths.controllers,
@@ -14,7 +13,7 @@ class Loader {
     #initialized = false;
 
     async initialize() {
-        if (this.#initialized || !IS_DEV) return;
+        if (this.#initialized || !Environment.isDev) return;
 
         for (const dir of DIRECTORIES) {
             await this.#loadDirectory(dir);
@@ -24,7 +23,7 @@ class Loader {
     }
 
     wrapHandler(handler) {
-        if (!IS_DEV) return handler;
+        if (!Environment.isDev) return handler;
 
         const info = this.#registry.get(handler);
         if (!info) return handler;

package/lib/Route/Manager.js

@@ -19,7 +19,6 @@ class Route {
     }
 
     static async setup(server) {
-        // Setup global route helper for SSR
         globalThis.route = (name, params, query) => this.route(name, params, query);
 
         const Kernel = await this.getKernel();
@@ -56,7 +55,6 @@ class Route {
         }
     }
 
-    // Get route manifest for client-side routing
     static getClientManifest() {
         const manifest = {};
         for (const route of this.#routes) {
@@ -66,7 +64,30 @@ class Route {
         }
         return manifest;
     }
-    
+
+    static match(pathname, method = "GET") {
+        for (const route of this.#routes) {
+            if (route.method !== method) continue;
+
+            const pattern = route.url
+                .replace(/:[^/]+/g, "([^/]+)")
+                .replace(/\//g, "\\/");
+            const regex = new RegExp(`^${pattern}$`);
+            const match = pathname.match(regex);
+
+            if (match) {
+                const paramNames = (route.url.match(/:[^/]+/g) || [])
+                    .map(p => p.slice(1));
+                const params = {};
+                paramNames.forEach((name, i) => {
+                    params[name] = match[i + 1];
+                });
+                return { handler: route.handler, params, route };
+            }
+        }
+        return null;
+    }
+
     static get (url, handler) {
         return this.#add("GET", url, handler);
     }