millas 0.2.23 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "A modern batteries-included backend framework for Node.js — built on Express, inspired by Laravel, Django, and FastAPI",
   "main": "src/index.js",
   "exports": {
@@ -51,7 +51,8 @@
     "nodemailer": "^6.9.0",
     "nunjucks": "^3.2.4",
     "ora": "5.4.1",
-    "sqlite3": "5.1.6"
+    "sqlite3": "5.1.6",
+    "node-cron": "^4.2.1"
   },
   "peerDependencies": {
     "express": "^4.18.0",

package/src/admin/Admin.js

@@ -104,11 +104,27 @@ class Admin {
 
   _setupNunjucks(expressApp) {
     const viewsDir = path.join(__dirname, 'views');
-    const env = nunjucks.configure(viewsDir, {
-      autoescape: true,
-      express:    expressApp,
-      noCache:    process.env.NODE_ENV !== 'production',
-    });
+    
+    // Check if nunjucks is already configured by the main app
+    const existingEnv = expressApp.get('nunjucksEnvironment');
+    let env;
+    
+    if (existingEnv) {
+      // Create a new environment that includes both search paths
+      const mainAppViewsDir = expressApp.get('views');
+      env = nunjucks.configure([viewsDir, mainAppViewsDir], {
+        autoescape: true,
+        express:    expressApp,
+        noCache:    process.env.NODE_ENV !== 'production',
+      });
+    } else {
+      env = nunjucks.configure(viewsDir, {
+        autoescape: true,
+        express:    expressApp,
+        noCache:    process.env.NODE_ENV !== 'production',
+      });
+      expressApp.set('nunjucksEnvironment', env);
+    }
 
     const resolveFkSlug = (tableName) => {
       if (!tableName) return null;

package/src/cli.js

@@ -3,6 +3,9 @@
 // Load .env before anything else so all commands have access to env vars
 require('dotenv').config();
 
+// Set CLI mode globally for all commands
+process.env.MILLAS_CLI_MODE = 'true';
+
 const { Command } = require('commander');
 const chalk = require('chalk');
 const program = new Command();
@@ -20,6 +23,7 @@ require('./commands/make')(program);
 require('./commands/migrate')(program);
 require('./commands/route')(program);
 require('./commands/queue')(program);
+require('./commands/schedule')(program);
 require('./commands/createsuperuser')(program);
 require('./commands/lang')(program);
 require('./commands/key')(program);

package/src/commands/queue.js

@@ -26,8 +26,7 @@ module.exports = function (program) {
       process.env.MILLAS_ROUTE_LIST = 'true'; // suppress server listen
       let app;
       try {
-        const bootstrap = require(bootstrapPath);
-        app = bootstrap.app;
+        app = await require(bootstrapPath);
       } catch (e) {
         console.error(chalk.red(`\n  ✖ Failed to load app: ${e.message}\n`));
         process.exit(1);

package/src/commands/route.js

@@ -20,7 +20,7 @@ module.exports = function (program) {
 
       let route;
       try {
-        const bootstrap = require(bootstrapPath);
+        const bootstrap = await require(bootstrapPath);
         route = bootstrap.route;
       } catch (err) {
         console.error(chalk.red(`\n  ✖ Failed to load routes: ${err.message}\n`));

package/src/commands/schedule.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+
+module.exports = function (program) {
+
+  program
+    .command('schedule:list')
+    .description('Show all scheduled tasks and their next run times')
+    .action(async () => {
+      const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
+      if (!fs.existsSync(bootstrapPath)) {
+        console.error(chalk.red('\n  ✖ Not inside a Millas project.\n'));
+        process.exit(1);
+      }
+
+      // Boot the app to get scheduler
+      let app;
+      try {
+        app = await require(bootstrapPath);
+      } catch (e) {
+        console.error(chalk.red(`\n  ✖ Failed to load app: ${e.message}\n`));
+        process.exit(1);
+      }
+
+      const scheduler = app.make('scheduler');
+      const tasks = scheduler.getTasks();
+
+      console.log();
+      if (tasks.length === 0) {
+        console.log(chalk.gray('  No scheduled tasks found.'));
+        console.log(chalk.gray('  Create routes/schedule.js to define scheduled tasks.'));
+      } else {
+        console.log(chalk.bold('  Scheduled Tasks\n'));
+        
+        for (const task of tasks) {
+          const status = task.isRunning() ? chalk.yellow('RUNNING') : chalk.green('READY');
+          const nextRun = task.lastRun 
+            ? `Last: ${task.lastRun.toLocaleString()}`
+            : chalk.gray('Never run');
+          
+          console.log(`  ${chalk.cyan(task.jobClass.name.padEnd(30))} ${status.padEnd(15)} ${nextRun}`);
+          
+          if (task.cronExpression) {
+            console.log(`    ${chalk.gray('Cron:')} ${task.cronExpression}`);
+          }
+          
+          if (Object.keys(task.parameters).length > 0) {
+            console.log(`    ${chalk.gray('Params:')} ${JSON.stringify(task.parameters)}`);
+          }
+          
+          if (task.failures.length > 0) {
+            const lastFailure = task.failures[task.failures.length - 1];
+            console.log(`    ${chalk.red('Last failure:')} ${lastFailure.error} (${lastFailure.timestamp.toLocaleString()})`);
+          }
+          
+          console.log();
+        }
+      }
+      
+      process.exit(0);
+    });
+
+  program
+    .command('schedule:test <taskName>')
+    .description('Run a specific scheduled task immediately for testing')
+    .action(async (taskName) => {
+      const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
+      if (!fs.existsSync(bootstrapPath)) {
+        console.error(chalk.red('\n  ✖ Not inside a Millas project.\n'));
+        process.exit(1);
+      }
+
+      // Boot the app
+      let app;
+      try {
+        app = await require(bootstrapPath);
+      } catch (e) {
+        console.error(chalk.red(`\n  ✖ Failed to load app: ${e.message}\n`));
+        process.exit(1);
+      }
+
+      const scheduler = app.make('scheduler');
+      const tasks = scheduler.getTasks();
+      const task = tasks.find(t => t.jobClass.name === taskName);
+
+      if (!task) {
+        console.error(chalk.red(`\n  ✖ Task "${taskName}" not found.\n`));
+        console.log(chalk.gray('  Available tasks:'));
+        tasks.forEach(t => console.log(chalk.gray(`    - ${t.jobClass.name}`)));
+        console.log();
+        process.exit(1);
+      }
+
+      console.log(chalk.blue(`\n  ▶ Running ${taskName}...\n`));
+
+      try {
+        await scheduler._executeTask(task, new Date());
+        console.log(chalk.green(`  ✔ ${taskName} completed successfully.\n`));
+      } catch (error) {
+        console.error(chalk.red(`  ✖ ${taskName} failed: ${error.message}\n`));
+        process.exit(1);
+      }
+
+      process.exit(0);
+    });
+
+  program
+    .command('make:task <name>')
+    .description('Generate a new scheduled task class')
+    .action(async (name) => {
+      const taskName = name.endsWith('Task') ? name : `${name}Task`;
+      const taskPath = path.resolve(process.cwd(), 'app', 'tasks', `${taskName}.js`);
+
+      // Ensure directory exists
+      await fs.ensureDir(path.dirname(taskPath));
+
+      // Check if file already exists
+      if (await fs.pathExists(taskPath)) {
+        console.error(chalk.red(`\n  ✖ Task ${taskName} already exists.\n`));
+        process.exit(1);
+      }
+
+      // Generate task class
+      const template = `'use strict';
+
+const { Job } = require('millas/core/queue');
+
+/**
+ * ${taskName}
+ *
+ * Scheduled task that runs automatically based on the schedule defined in routes/schedule.js
+ *
+ * Usage in routes/schedule.js:
+ *   Schedule.job(${taskName}).daily().at('09:00');
+ */
+class ${taskName} extends Job {
+  /**
+   * Constructor - DI container will inject dependencies automatically
+   */
+  constructor(/* inject dependencies here */) {
+    super();
+    // Store injected dependencies
+  }
+
+  /**
+   * Execute the scheduled task
+   */
+  async handle() {
+    // Implement your scheduled task logic here
+    console.log('${taskName} is running...');
+  }
+
+  /**
+   * Handle task failure (optional)
+   */
+  async failed(error) {
+    console.error('${taskName} failed:', error.message);
+  }
+}
+
+module.exports = ${taskName};
+`;
+
+      await fs.writeFile(taskPath, template);
+
+      console.log(chalk.green(`\n  ✔ Task created: ${taskPath}`));
+      console.log(chalk.gray('\n  Next steps:'));
+      console.log(chalk.gray(`    1. Implement the handle() method in ${taskName}`));
+      console.log(chalk.gray(`    2. Add the task to routes/schedule.js:`));
+      console.log(chalk.gray(`       Schedule.job(${taskName}).daily().at('09:00');`));
+      console.log();
+    });
+};

package/src/container/AppInitializer.js

@@ -58,6 +58,7 @@ class AppInitializer {
         if (!process.env.MILLAS_CLI_MODE) {
             await this._serve();
         }
+
         return this._kernel;
     }
 
@@ -107,6 +108,12 @@ class AppInitializer {
 
         this._kernel._container.instance('basePath', basePath);
 
+        // ── View engine ─────────────────────────────────────────────────────────────────
+        // Auto-configure Nunjucks as the default template engine.
+        // Looks for views/ in the project root. Zero config required.
+        // Disable via config/app.js: { views: false }
+        this._setupViewEngine(expressApp, basePath, appConfig);
+
         // ── Static file serving ───────────────────────────────────────────────
         // Auto-serve each storage disk that has a baseUrl configured.
         // Mirrors Laravel's public disk serving — zero config required.
@@ -182,6 +189,65 @@ class AppInitializer {
 
     // ── Internal ───────────────────────────────────────────────────────────────
 
+    _setupViewEngine(expressApp, basePath, appConfig) {
+        const path = require('path');
+        const fs   = require('fs');
+
+        // Opt-out: views: false in config/app.js
+        if (appConfig.views === false) return;
+
+        const viewsConfig = appConfig.views || {};
+        const viewsDir    = path.isAbsolute(viewsConfig.path || '')
+            ? viewsConfig.path
+            : path.join(basePath, viewsConfig.path || 'resources/views');
+
+        // Don't configure if views directory doesn't exist
+        if (!fs.existsSync(viewsDir)) return;
+
+        // Serve public/ directory for CSS, JS, images used in views
+        const publicDir = path.join(basePath, viewsConfig.public || 'public');
+        if (fs.existsSync(publicDir)) {
+            expressApp.use(express.static(publicDir));
+        }
+
+        const engine = viewsConfig.engine || 'nunjucks';
+
+        if (engine === 'nunjucks') {
+            // nunjucks is a core Millas dependency — always available
+            const nunjucks = require('nunjucks');
+
+            // Check if nunjucks is already configured for this express app
+            const existingEnv = expressApp.get('nunjucksEnvironment');
+            let env;
+            
+            if (existingEnv) {
+                // Admin panel will reconfigure with multiple search paths
+                env = existingEnv;
+            } else {
+                env = nunjucks.configure(viewsDir, {
+                    autoescape:    viewsConfig.autoescape    ?? true,
+                    watch:         viewsConfig.watch         ?? (process.env.NODE_ENV !== 'production'),
+                    noCache:       viewsConfig.noCache       ?? (process.env.NODE_ENV !== 'production'),
+                    throwOnUndefined: viewsConfig.throwOnUndefined ?? false,
+                    express:       expressApp,
+                });
+                // Store reference for later use
+                expressApp.set('nunjucksEnvironment', env);
+            }
+
+            // Support both .html and .njk extensions
+            expressApp.set('view engine', 'html');
+            expressApp.engine('html', env.render.bind(env));
+            expressApp.engine('njk',  env.render.bind(env));
+            expressApp.set('views', viewsDir);
+
+        } else {
+            // Custom engine — user must configure it themselves via .use()
+            expressApp.set('views', viewsDir);
+            expressApp.set('view engine', engine);
+        }
+    }
+
     _serveStorageDisks(expressApp, basePath) {
         const express = require('express');
         const path    = require('path');
@@ -286,10 +352,18 @@ class AppInitializer {
             if (p) providers.push(p);
         }
 
-        // ── 9. i18n — opt-in via config/app.js use_i18n: true ───────────────
+        // ── 9. Scheduler — always on unless explicitly disabled ──────────────
+        // Built-in task scheduler that runs alongside the HTTP server.
+        // Automatically loads and executes scheduled tasks from routes/schedule.js.
+        if (cfg.scheduler !== false) {
+            const p = load('../scheduler/SchedulerServiceProvider');
+            if (p) providers.push(p);
+        }
+
+        // ── 10. i18n — opt-in via config/app.js use_i18n: true ──────────────
         // Mirrors Django's USE_I18N = True in settings.py.
         // Booted last so translations are available in all request handlers.
-        // ── 9. Encryption — always on (APP_KEY drives it) ────────────────────
+        // ── 10. Encryption — always on (APP_KEY drives it) ────────────────────
         // Mirrors Laravel: the encrypter is always bound so Crypt / Encrypt
         // facades work out of the box. If APP_KEY is absent a clear error is
         // thrown on first use, not at boot — apps without encryption still start.

package/src/container/HttpServer.js

@@ -134,17 +134,25 @@ class HttpServer {
 
     _handleSignals() {
         const shutdown = async (signal) => {
+            process.stdout.write(`\n  Shutting down (${signal})…\n`);
+            
+            if (typeof this._options.onShutdown === 'function') {
+                try {
+                    await this._options.onShutdown();
+                } catch (err) {
+                    console.error('Shutdown error:', err.message);
+                }
+            }
+            
+            // Stop scheduler if it exists
+            try {
+                const scheduler = this._app._container.make('scheduler');
+                await scheduler.stop();
+            } catch {
+                // Scheduler not registered or already stopped
+            }
+            
             process.exit(0);
-            // process.stdout.write(`\n  Shutting down (${signal})…\n`);
-            //
-            // if (typeof this._options.onShutdown === 'function') {
-            //     try {
-            //         await this._options.onShutdown();
-            //     } catch {
-            //     }
-            // }
-            //
-            // await this._app.shutdown(0);
         };
 
         process.once('SIGTERM', () => shutdown("SIGTERM"));

package/src/core/foundation.js

@@ -70,4 +70,6 @@ module.exports = {
   // Support
   Str, FluentString,
   Log: require('../logger').Log,
+  // Scheduler
+  TaskScheduler: require('../scheduler').TaskScheduler,
 };

package/src/core/scheduler.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { TaskScheduler, SchedulerServiceProvider } = require('../scheduler');
+
+module.exports = {
+  TaskScheduler,
+  SchedulerServiceProvider,
+};

package/src/errors/ErrorRenderer.js

@@ -55,11 +55,12 @@ class ErrorRenderer {
    * Render an error to the response — JSON or HTML based on Accept header.
    */
   static render(err, req, res) {
-    const status  = err.status || err.statusCode || 500;
-    const isDev   = process.env.NODE_ENV !== 'production';
-    const wantsHtml = ErrorRenderer._wantsHtml(req);
+   try {
+     const status  = err.status || err.statusCode || 500;
+     const isDev   = process.env.NODE_ENV !== 'production';
+     const wantsHtml = ErrorRenderer._wantsHtml(req);
 
-    res.status(status);
+     res.status(status);
 
     if (!wantsHtml) {
       // ── JSON response ──────────────────────────────────────────────────────
@@ -73,6 +74,31 @@ class ErrorRenderer {
       return res.json(body);
     }
 
+
+    // Check for custom error view in resources/views/errors/
+    // e.g. resources/views/errors/404.html, resources/views/errors/500.html
+    const customView = ErrorRenderer._findCustomErrorView(status);
+    if (customView) {
+      try {
+        return res.render(customView, {
+          status,
+          message:     err.message,
+          error:       err,
+          isDev,
+          statusTitle: ErrorRenderer._statusTitle(status),
+        }, (renderErr, html) => {
+          if (renderErr) {
+            // View engine error — fall back to built-in pages
+            if (!isDev || status < 500 && !err._forceDebug) {
+              return res.send(ErrorRenderer._renderSimple(status, err.message));
+            }
+            return res.send(ErrorRenderer._renderDebug(err, req, status));
+          }
+          res.send(html);
+        });
+      } catch { /* view engine not configured — fall through */ }
+    }
+
     if (!isDev || status < 500 && !err._forceDebug) {
       // ── Production / 4xx HTML ──────────────────────────────────────────────
       return res.send(ErrorRenderer._renderSimple(status, err.message));
@@ -80,10 +106,32 @@ class ErrorRenderer {
 
     // ── Development HTML — full debug page ────────────────────────────────────
     res.send(ErrorRenderer._renderDebug(err, req, status));
+   }catch (e){
+     console.log(e)
+     res.send("something went wrong")
+   }
   }
 
   // ─── HTML renderers ────────────────────────────────────────────────────────
 
+  static _findCustomErrorView(status) {
+    const fs   = require('fs');
+    const path = require('path');
+    const viewsDir = path.join(process.cwd(), 'resources', 'views', 'errors');
+    const candidates = [
+      path.join(viewsDir, `${status}.html`),
+      path.join(viewsDir, `${status}.njk`),
+      path.join(viewsDir, 'error.html'),
+      path.join(viewsDir, 'error.njk'),
+    ];
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return `errors/${require('path').basename(candidate)}`;
+      }
+    }
+    return null;
+  }
+
   static _renderSimple(status, message) {
     const title = ErrorRenderer._statusTitle(status);
     return `<!DOCTYPE html>
@@ -139,6 +187,24 @@ class ErrorRenderer {
       'Uptime':      `${Math.floor(process.uptime())}s`,
     };
 
+    // Host details for EINVALIDHOST errors
+    const hostDetailsHtml = err._hostDetails ? `
+    <!-- Host Details -->
+    <div class="section">
+      <div class="section-header" onclick="toggle(this)">
+        <span>Host Configuration</span>
+        <span class="toggle">▾</span>
+      </div>
+      <div class="section-body">
+        <table class="info-table">
+          <tr><td>Received Host</td><td style="font-family:monospace;color:var(--red)">${_esc(err._hostDetails.receivedHost)}</td></tr>
+          <tr><td>Allowed Hosts</td><td><pre class="json-val">${_esc(JSON.stringify(err._hostDetails.allowedHosts, null, 2))}</pre></td></tr>
+          <tr><td>Environment</td><td>${_esc(err._hostDetails.environment)}</td></tr>
+          ${err._hostDetails.suggestion ? `<tr><td>Suggestion</td><td style="color:var(--blue)">${_esc(err._hostDetails.suggestion)}</td></tr>` : ''}
+        </table>
+      </div>
+    </div>` : '';
+
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -466,6 +532,8 @@ class ErrorRenderer {
       </div>
     </div>
 
+    ${hostDetailsHtml}
+
     ${err.errors ? `
     <!-- Validation errors -->
     <div class="section">

package/src/facades/Database.js

@@ -1,64 +1,53 @@
 'use strict';
 
-const Facade = require('./Facade');
+const { createFacade } = require('./Facade');
 
 /**
- * Database facade — direct access to the knex connection.
+ * Database facade — Laravel-style DB access.
  *
  * Usage:
+ *   const { Database } = require('millas');
+ *   // or
  *   const Database = require('millas/facades/Database');
  *
  *   // Raw SQL
- *   const result = await Database.raw('SELECT NOW()');
+ *   const users = await Database.select('SELECT * FROM users WHERE id = ?', [1]);
+ *   await Database.insert('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+ *   await Database.update('UPDATE users SET name = ? WHERE id = ?', ['Jane', 1]);
+ *   await Database.delete('DELETE FROM users WHERE id = ?', [1]);
  *
- *   // Knex query builder
- *   const rows = await Database.table('posts').where('published', true).select('*');
+ *   // Query Builder (most common)
+ *   const users = await Database.table('users').get();
+ *   const user = await Database.table('users').where('id', 1).first();
+ *   await Database.table('users').insert({ name: 'John', email: 'john@example.com' });
+ *   await Database.table('users').where('id', 1).update({ name: 'Jane' });
+ *   await Database.table('users').where('id', 1).delete();
  *
- *   // Named connection
- *   const rows = await Database.connection('replica').raw('SELECT 1');
+ *   // Transactions
+ *   await Database.transaction(async (trx) => {
+ *     await trx.table('accounts').update({ balance: 100 });
+ *     await trx.table('transactions').insert({ amount: 100 });
+ *   });
+ *
+ *   // Multiple connections
+ *   await Database.connection('mysql').table('users').get();
+ *
+ *   // Raw expressions
+ *   await Database.table('users').select(Database.raw('COUNT(*) as total')).first();
+ *
+ * @class
+ * @property {function(string): *}                    table       - Query builder for a table
+ * @property {function(string, array=): Promise<*>}   raw         - Execute raw SQL
+ * @property {function(string, array=): Promise<*>}   select      - SELECT query
+ * @property {function(string, array=): Promise<*>}   insert      - INSERT query
+ * @property {function(string, array=): Promise<*>}   update      - UPDATE query
+ * @property {function(string, array=): Promise<*>}   delete      - DELETE query
+ * @property {function(function): Promise<*>}         transaction - Run queries in transaction
+ * @property {function(string=): *}                   connection  - Get named connection
+ *
+ * @see src/orm/drivers/DatabaseManager.js
  */
-class Database {
-  static _resolveInstance() {
-    const DatabaseManager = require('../orm/drivers/DatabaseManager');
-    return DatabaseManager.connection();
-  }
+class Database extends createFacade('db') {
 }
 
-// Proxy every static call to the knex connection
-module.exports = new Proxy(Database, {
-  get(target, prop) {
-    // Let real static members through
-    if (prop in target || prop === 'then' || prop === 'catch') {
-      return target[prop];
-    }
-    if (typeof prop === 'symbol') return target[prop];
-
-    // Special case: raw() — normalize result across dialects
-    if (prop === 'raw') {
-      return async (sql, bindings) => {
-        const db = Database._resolveInstance();
-        const result = await db.raw(sql, bindings);
-        // Postgres returns { rows: [...], command, rowCount, ... }
-        // SQLite/MySQL return [rows, fields] or just rows
-        if (result && result.rows) return result.rows;
-        if (Array.isArray(result)) return result[0] ?? result;
-        return result;
-      };
-    }
-
-    // Special case: connection(name) returns a named knex instance
-    if (prop === 'connection') {
-      return (name) => {
-        const DatabaseManager = require('../orm/drivers/DatabaseManager');
-        return DatabaseManager.connection(name || null);
-      };
-    }
-
-    // Proxy everything else to the default knex connection
-    return (...args) => {
-      const db = Database._resolveInstance();
-      if (typeof db[prop] !== 'function') return db[prop];
-      return db[prop](...args);
-    };
-  },
-});
+module.exports = Database;

package/src/facades/Schedule.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const Facade = require('./Facade');
+
+/**
+ * Schedule Facade
+ *
+ * Provides easy access to the task scheduler for defining scheduled tasks.
+ *
+ * Usage:
+ *   const { Schedule } = require('millas/facades');
+ *   
+ *   Schedule.job(SendEmailJob).daily().at('09:00');
+ *   Schedule.job(CleanupJob).hourly();
+ */
+class Schedule extends Facade {
+  static getAccessor() {
+    return 'scheduler';
+  }
+}
+
+module.exports = Schedule;