millas 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "A modern batteries-included backend framework for Node.js — built on Express, inspired by Laravel, Django, and FastAPI",
   "main": "src/index.js",
   "exports": {

package/src/admin/views/layouts/base.njk

@@ -1137,7 +1137,7 @@
       const prefix = '{{ adminPrefix }}';
       const resources = [
         {% for r in resources %}
-        { slug: '{{ r.slug }}', index: {{ r.index }} }{% if not loop.last %},{% endif %}
+        { slug: '{{ r.slug }}', index: {{ r.index |  default('null')}} }{% if not loop.last %},{% endif %}
         {% endfor %}
       ];
 

package/src/index.js

@@ -1,5 +1,21 @@
 'use strict';
 
+// ── Logger ────────────────────────────────────────────────────────
+const {
+  Log,
+  Logger,
+  LEVELS,
+  LEVEL_NAMES,
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+} = require('./logger/index');
+const LogServiceProvider = require('./providers/LogServiceProvider');
+
 // ── HTTP Layer ────────────────────────────────────────────────────
 const Controller         = require('./controller/Controller');
 const Middleware         = require('./middleware/Middleware');
@@ -16,13 +32,8 @@ const ServiceProvider    = require('./providers/ServiceProvider');
 const ProviderRegistry   = require('./providers/ProviderRegistry');
 
 // ── ORM ───────────────────────────────────────────────────────────
-const {
-  Model, fields, QueryBuilder, DatabaseManager,
-  SchemaBuilder, MigrationRunner, ModelInspector,
-  Q, LookupParser,
-  Sum, Avg, Min, Max, Count, AggregateExpression,
-  HasOne, HasMany, BelongsTo, BelongsToMany,
-} = require('./orm');
+const { Model, fields, QueryBuilder, DatabaseManager,
+        SchemaBuilder, MigrationRunner, ModelInspector } = require('./orm');
 const DatabaseServiceProvider = require('./providers/DatabaseServiceProvider');
 
 // ── Auth ──────────────────────────────────────────────────────────
@@ -65,6 +76,11 @@ const Storage     = require('./storage/Storage');
 const LocalDriver = require('./storage/drivers/LocalDriver');
 
 module.exports = {
+  // Logger
+  Log, Logger, LEVELS, LEVEL_NAMES,
+  PrettyFormatter, JsonFormatter, SimpleFormatter,
+  ConsoleChannel, FileChannel, NullChannel, StackChannel,
+  LogServiceProvider,
   // HTTP
   Controller, Middleware, MiddlewarePipeline,
   CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
@@ -73,9 +89,6 @@ module.exports = {
   // ORM
   Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
   MigrationRunner, ModelInspector, DatabaseServiceProvider,
-  Q, LookupParser,
-  Sum, Avg, Min, Max, Count, AggregateExpression,
-  HasOne, HasMany, BelongsTo, BelongsToMany,
   // Auth
   Auth, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware,
   AuthController, AuthServiceProvider,

package/src/logger/Logger.js

@@ -0,0 +1,341 @@
+'use strict';
+
+const { LEVELS } = require('./levels');
+
+/**
+ * Logger
+ *
+ * The Millas application logger. Inspired by Android's Timber library —
+ * a small, extensible logging tree where you plant channels ("trees")
+ * and log through a unified facade.
+ *
+ * ── Quick start ────────────────────────────────────────────────────────────
+ *
+ *   const { Log } = require('millas');
+ *
+ *   Log.i('Server started on port 3000');
+ *   Log.d('QueryBuilder', 'SELECT * FROM users', { duration: '4ms' });
+ *   Log.w('Auth', 'Token expiring soon', { userId: 5 });
+ *   Log.e('Database', 'Connection failed', error);
+ *   Log.wtf('Payment', 'Stripe returned null transaction');
+ *
+ * ── Tag chaining (like Timber.tag()) ───────────────────────────────────────
+ *
+ *   Log.tag('UserService').i('User created', { id: 5 });
+ *   Log.tag('Mailer').d('Sending email', { to: 'a@b.com' });
+ *
+ * ── Full signatures ────────────────────────────────────────────────────────
+ *
+ *   Log.v(message)
+ *   Log.v(tag, message)
+ *   Log.v(tag, message, context)        // context = object | primitive
+ *   Log.v(tag, message, error)          // error = Error instance
+ *   Log.v(tag, message, context, error)
+ *
+ * ── Configuration ──────────────────────────────────────────────────────────
+ *
+ *   Log.configure({
+ *     minLevel: LEVELS.INFO,     // filter out VERBOSE + DEBUG in production
+ *     channel:  new StackChannel([
+ *       new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *       new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.WARN }),
+ *     ]),
+ *   });
+ *
+ * ── Request logging (Django-style) ─────────────────────────────────────────
+ *
+ *   // In bootstrap/app.js — installed automatically by LogServiceProvider
+ *   app.use(Log.requestMiddleware());
+ *   // Logs: [2026-03-15 12:00:00] I  HTTP  POST /api/users 201 14ms
+ */
+class Logger {
+  constructor() {
+    this._channel    = null;      // primary channel (StackChannel in production)
+    this._minLevel   = LEVELS.DEBUG;
+    this._tag        = null;      // set by .tag() for a single chained call
+    this._defaultTag = 'App';
+  }
+
+  // ─── Configuration ────────────────────────────────────────────────────────
+
+  /**
+   * Configure the logger.
+   *
+   * @param {object} options
+   * @param {object}  [options.channel]    — a channel or StackChannel instance
+   * @param {number}  [options.minLevel]   — minimum level to emit (LEVELS.*)
+   * @param {string}  [options.defaultTag] — fallback tag when none supplied
+   */
+  configure(options = {}) {
+    if (options.channel  !== undefined) this._channel    = options.channel;
+    if (options.minLevel !== undefined) this._minLevel   = options.minLevel;
+    if (options.defaultTag !== undefined) this._defaultTag = options.defaultTag;
+    return this;
+  }
+
+  /**
+   * Set a one-shot tag for the next log call.
+   * Returns a proxy that resets the tag after the call.
+   *
+   *   Log.tag('UserService').i('Created user', { id: 5 });
+   */
+  tag(name) {
+    // Return a lightweight proxy that carries the tag
+    return new TaggedLogger(this, name);
+  }
+
+  // ─── Timber-style level methods ───────────────────────────────────────────
+
+  /** VERBOSE — very detailed tracing, usually disabled in production */
+  v(...args) { return this._log(LEVELS.VERBOSE, null, ...args); }
+
+  /** DEBUG — development diagnostics */
+  d(...args) { return this._log(LEVELS.DEBUG, null, ...args); }
+
+  /** INFO — normal operational messages */
+  i(...args) { return this._log(LEVELS.INFO, null, ...args); }
+
+  /** WARN — unexpected but recoverable */
+  w(...args) { return this._log(LEVELS.WARN, null, ...args); }
+
+  /** ERROR — something failed */
+  e(...args) { return this._log(LEVELS.ERROR, null, ...args); }
+
+  /**
+   * WTF — "What a Terrible Failure"
+   * A condition that should NEVER happen. Always logged regardless of minLevel.
+   * Triggers a big visual warning in the console.
+   */
+  wtf(...args) { return this._log(LEVELS.WTF, null, ...args); }
+
+  // ─── Verbose aliases (for readability) ────────────────────────────────────
+
+  /** Alias for i() */
+  info(...args)    { return this.i(...args); }
+  /** Alias for d() */
+  debug(...args)   { return this.d(...args); }
+  /** Alias for w() */
+  warn(...args)    { return this.w(...args); }
+  /** Alias for e() */
+  error(...args)   { return this.e(...args); }
+  /** Alias for v() */
+  verbose(...args) { return this.v(...args); }
+
+  // ─── Request middleware (Django-style) ────────────────────────────────────
+
+  /**
+   * Returns an Express middleware that logs every HTTP request.
+   *
+   * Log format:
+   *   POST /api/users 201 14ms  (coloured by status)
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.includeQuery=false]   — append ?query to path
+   * @param {boolean} [options.includeBody=false]    — log request body (be careful with PII)
+   * @param {number}  [options.slowThreshold=1000]   — warn if response > Nms
+   * @param {Function} [options.skip]                — (req, res) => bool — skip certain routes
+   */
+  requestMiddleware(options = {}) {
+    const self = this;
+    const {
+      includeQuery   = false,
+      includeBody    = false,
+      slowThreshold  = 1000,
+      skip,
+    } = options;
+
+    return function millaRequestLogger(req, res, next) {
+      if (typeof skip === 'function' && skip(req, res)) return next();
+
+      const start = Date.now();
+
+      res.on('finish', () => {
+        const ms     = Date.now() - start;
+        const status = res.statusCode;
+        const method = req.method;
+        let   url    = req.path || req.url || '/';
+
+        if (includeQuery && req.url && req.url.includes('?')) {
+          url = req.url;
+        }
+
+        // Determine log level from status code — mirrors Django's request logging
+        let level;
+        if      (status >= 500) level = LEVELS.ERROR;
+        else if (status >= 400) level = LEVELS.WARN;
+        else if (ms > slowThreshold) level = LEVELS.WARN;
+        else                    level = LEVELS.INFO;
+
+        const ctx = {
+          method,
+          status,
+          ms,
+          ip: req.ip || req.connection?.remoteAddress,
+        };
+
+        if (includeBody && req.body && Object.keys(req.body).length) {
+          ctx.body = req.body;
+        }
+
+        if (ms > slowThreshold) {
+          ctx.slow = true;
+        }
+
+        self._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
+      });
+
+      next();
+    };
+  }
+
+  // ─── Timer utility ────────────────────────────────────────────────────────
+
+  /**
+   * Start a named timer. Returns a function that logs the elapsed time.
+   *
+   *   const done = Log.time('Database query');
+   *   await db.query(...);
+   *   done(); // → I  Timer  Database query: 42ms
+   */
+  time(label) {
+    const start = Date.now();
+    return (extraTag) => {
+      const ms = Date.now() - start;
+      this._log(LEVELS.DEBUG, extraTag || 'Timer', `${label}: ${ms}ms`, { ms });
+      return ms;
+    };
+  }
+
+  /**
+   * Wrap an async function and log its execution time.
+   *
+   *   const result = await Log.timed('fetchUsers', () => User.all());
+   */
+  async timed(label, fn, tag) {
+    const done = this.time(label);
+    try {
+      const result = await fn();
+      done(tag);
+      return result;
+    } catch (err) {
+      this._log(LEVELS.ERROR, tag || 'Timer', `${label} threw`, err);
+      throw err;
+    }
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  /**
+   * Core dispatch method.
+   *
+   * Signatures:
+   *   _log(level, forcedTag, message)
+   *   _log(level, forcedTag, tag, message)
+   *   _log(level, forcedTag, tag, message, context)
+   *   _log(level, forcedTag, tag, message, context, error)
+   *   _log(level, forcedTag, tag, message, error)          // Error as 4th arg
+   */
+  _log(level, forcedTag, ...args) {
+    // WTF is always emitted regardless of minLevel
+    if (level !== LEVELS.WTF && level < this._minLevel) return;
+
+    const entry = this._parse(level, forcedTag, args);
+    this._emit(entry);
+  }
+
+  _parse(level, forcedTag, args) {
+    let tag, message, context, error;
+
+    // Normalise arguments
+    if (args.length === 0) {
+      message = '';
+    } else if (args.length === 1) {
+      // Single arg — could be a string message or an Error
+      if (args[0] instanceof Error) {
+        error   = args[0];
+        message = error.message;
+      } else {
+        message = String(args[0]);
+      }
+    } else if (args.length === 2) {
+      // (tag, message) OR (message, context/error)
+      if (typeof args[0] === 'string' && typeof args[1] === 'string') {
+        // Both strings: tag + message
+        tag     = args[0];
+        message = args[1];
+      } else if (args[1] instanceof Error) {
+        message = String(args[0]);
+        error   = args[1];
+      } else if (typeof args[0] === 'string') {
+        message = args[0];
+        context = args[1];
+      } else {
+        message = String(args[0]);
+        context = args[1];
+      }
+    } else if (args.length === 3) {
+      // (tag, message, context/error)
+      tag     = String(args[0]);
+      message = String(args[1]);
+      if (args[2] instanceof Error) error   = args[2];
+      else                          context = args[2];
+    } else {
+      // (tag, message, context, error)
+      tag     = String(args[0]);
+      message = String(args[1]);
+      context = args[2];
+      error   = args[3] instanceof Error ? args[3] : undefined;
+    }
+
+    return {
+      level,
+      tag:       forcedTag || tag || this._defaultTag,
+      message:   message   || '',
+      context,
+      error,
+      timestamp: new Date().toISOString(),
+      pid:       process.pid,
+    };
+  }
+
+  _emit(entry) {
+    if (!this._channel) {
+      // No channel configured — fall back to raw console so nothing is lost
+      const prefix = `[${entry.level}] ${entry.tag}: ${entry.message}`;
+      if (entry.level >= 4) process.stderr.write(prefix + '\n');
+      else                  process.stdout.write(prefix + '\n');
+      return;
+    }
+
+    try {
+      this._channel.write(entry);
+    } catch (err) {
+      // Never crash the app because of a logging failure
+      process.stderr.write(`[millas logger] channel error: ${err.message}\n`);
+    }
+  }
+}
+
+// ─── TaggedLogger — returned by Log.tag() ─────────────────────────────────────
+
+class TaggedLogger {
+  constructor(logger, tag) {
+    this._logger = logger;
+    this._tag    = tag;
+  }
+
+  v(...args) { return this._logger._log(LEVELS.VERBOSE, this._tag, ...args); }
+  d(...args) { return this._logger._log(LEVELS.DEBUG,   this._tag, ...args); }
+  i(...args) { return this._logger._log(LEVELS.INFO,    this._tag, ...args); }
+  w(...args) { return this._logger._log(LEVELS.WARN,    this._tag, ...args); }
+  e(...args) { return this._logger._log(LEVELS.ERROR,   this._tag, ...args); }
+  wtf(...args) { return this._logger._log(LEVELS.WTF,  this._tag, ...args); }
+
+  info(...args)    { return this.i(...args); }
+  debug(...args)   { return this.d(...args); }
+  warn(...args)    { return this.w(...args); }
+  error(...args)   { return this.e(...args); }
+  verbose(...args) { return this.v(...args); }
+}
+
+module.exports = Logger;

package/src/logger/channels/ConsoleChannel.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * ConsoleChannel
+ *
+ * Writes log entries to process.stdout (levels < ERROR) or
+ * process.stderr (ERROR and WTF).
+ *
+ * Usage in config/logging.js:
+ *   new ConsoleChannel({ formatter: new PrettyFormatter() })
+ */
+class ConsoleChannel {
+  /**
+   * @param {object} options
+   * @param {object} options.formatter  — formatter instance (PrettyFormatter, JsonFormatter, …)
+   * @param {number} [options.minLevel] — minimum level to output (default: 0 = all)
+   */
+  constructor(options = {}) {
+    this.formatter = options.formatter;
+    this.minLevel  = options.minLevel ?? 0;
+  }
+
+  write(entry) {
+    if (entry.level < this.minLevel) return;
+
+    const output = this.formatter
+      ? this.formatter.format(entry)
+      : `[${entry.level}] ${entry.message}`;
+
+    // Route errors to stderr
+    if (entry.level >= 4) {
+      process.stderr.write(output + '\n');
+    } else {
+      process.stdout.write(output + '\n');
+    }
+  }
+}
+
+module.exports = ConsoleChannel;

package/src/logger/channels/FileChannel.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * FileChannel
+ *
+ * Writes log entries to daily rotating files.
+ *   storage/logs/millas-2026-03-15.log
+ *   storage/logs/millas-2026-03-16.log
+ *   …
+ *
+ * Uses Node's built-in fs — no external log-rotation library needed.
+ * Files are appended synchronously to avoid losing entries on crash.
+ *
+ * Usage in config/logging.js:
+ *   new FileChannel({
+ *     path:      'storage/logs',
+ *     prefix:    'millas',
+ *     formatter: new SimpleFormatter(),
+ *     minLevel:  LEVELS.INFO,
+ *     maxFiles:  30,   // keep 30 days of logs
+ *   })
+ */
+class FileChannel {
+  /**
+   * @param {object} options
+   * @param {string}  [options.path]       — directory path (default: storage/logs)
+   * @param {string}  [options.prefix]     — filename prefix (default: 'millas')
+   * @param {object}  [options.formatter]  — formatter instance
+   * @param {number}  [options.minLevel]   — minimum level (default: 0)
+   * @param {number}  [options.maxFiles]   — max daily files to retain (default: 30)
+   */
+  constructor(options = {}) {
+    this._dir       = path.resolve(process.cwd(), options.path || 'storage/logs');
+    this._prefix    = options.prefix    || 'millas';
+    this.formatter  = options.formatter;
+    this.minLevel   = options.minLevel  ?? 0;
+    this._maxFiles  = options.maxFiles  ?? 30;
+    this._lastDate  = null;
+    this._stream    = null;
+    this._ensuredDir = false;
+  }
+
+  write(entry) {
+    if (entry.level < this.minLevel) return;
+
+    try {
+      this._ensureDir();
+
+      const today = new Date().toISOString().slice(0, 10);
+      if (today !== this._lastDate) {
+        this._rotateStream(today);
+        this._pruneOldFiles();
+      }
+
+      const line = this.formatter
+        ? this.formatter.format(entry)
+        : `[${entry.timestamp}] [${entry.level}] ${entry.message}`;
+
+      fs.appendFileSync(this._currentPath, line + '\n', 'utf8');
+    } catch (err) {
+      // Never crash the app because of a logging failure
+      process.stderr.write(`[millas logger] FileChannel write error: ${err.message}\n`);
+    }
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────────
+
+  _ensureDir() {
+    if (this._ensuredDir) return;
+    fs.mkdirSync(this._dir, { recursive: true });
+    this._ensuredDir = true;
+  }
+
+  _rotateStream(date) {
+    this._lastDate    = date;
+    this._currentPath = path.join(this._dir, `${this._prefix}-${date}.log`);
+  }
+
+  _pruneOldFiles() {
+    try {
+      const files = fs.readdirSync(this._dir)
+        .filter(f => f.startsWith(this._prefix + '-') && f.endsWith('.log'))
+        .sort(); // ISO date prefix sorts chronologically
+
+      const toDelete = files.slice(0, Math.max(0, files.length - this._maxFiles));
+      for (const f of toDelete) {
+        try { fs.unlinkSync(path.join(this._dir, f)); } catch {}
+      }
+    } catch {}
+  }
+
+  /** Current log file path (useful for tooling). */
+  get currentFile() {
+    return this._currentPath || null;
+  }
+}
+
+module.exports = FileChannel;

package/src/logger/channels/index.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * NullChannel
+ *
+ * Silently discards all log entries.
+ * Useful in tests where you want to suppress all output.
+ *
+ *   Log.configure({ channels: [new NullChannel()] });
+ */
+class NullChannel {
+  write() { /* intentionally empty */ }
+}
+
+/**
+ * StackChannel
+ *
+ * Fans a single log entry out to multiple channels simultaneously.
+ * This is the standard "stack" pattern — one channel for console,
+ * another for file, optionally one for an external service.
+ *
+ *   new StackChannel([
+ *     new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *     new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.INFO }),
+ *   ])
+ */
+class StackChannel {
+  /**
+   * @param {Array} channels — array of channel instances
+   */
+  constructor(channels = []) {
+    this._channels = channels;
+  }
+
+  /** Add a channel at runtime. */
+  add(channel) {
+    this._channels.push(channel);
+    return this;
+  }
+
+  write(entry) {
+    for (const ch of this._channels) {
+      try { ch.write(entry); } catch {}
+    }
+  }
+}
+
+module.exports = { NullChannel, StackChannel };

package/src/logger/formatters/JsonFormatter.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { LEVEL_NAMES } = require('../levels');
+
+/**
+ * JsonFormatter
+ *
+ * Emits one JSON object per log entry — ideal for production environments
+ * where logs are shipped to Datadog, Elasticsearch, CloudWatch, etc.
+ *
+ * Output (one line per entry):
+ *   {"ts":"2026-03-15T12:00:00.000Z","level":"INFO","tag":"Auth","msg":"Login","ctx":{...}}
+ */
+class JsonFormatter {
+  /**
+   * @param {object} options
+   * @param {boolean} [options.pretty=false]   — pretty-print JSON (for debugging)
+   * @param {object}  [options.extra]          — static fields merged into every entry (e.g. service name)
+   */
+  constructor(options = {}) {
+    this.pretty = options.pretty || false;
+    this.extra  = options.extra  || {};
+  }
+
+  format(entry) {
+    const { level, tag, message, context, error, timestamp } = entry;
+
+    const record = {
+      ts:    timestamp || new Date().toISOString(),
+      level: LEVEL_NAMES[level] || String(level),
+      ...this.extra,
+    };
+
+    if (tag)     record.tag = tag;
+    record.msg = message;
+    if (context !== undefined && context !== null) record.ctx = context;
+
+    if (error instanceof Error) {
+      record.error = {
+        message: error.message,
+        name:    error.name,
+        stack:   error.stack,
+      };
+    }
+
+    return this.pretty
+      ? JSON.stringify(record, null, 2)
+      : JSON.stringify(record);
+  }
+}
+
+module.exports = JsonFormatter;

package/src/logger/formatters/PrettyFormatter.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { LEVEL_NAMES, LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD, DIM } = require('../levels');
+
+/**
+ * PrettyFormatter
+ *
+ * Colourful, human-readable output. Designed for development.
+ * Inspired by Timber (Android) and Laravel's log formatting.
+ *
+ * Output:
+ *   [2026-03-15 12:00:00] I  UserController  User #5 logged in
+ *   [2026-03-15 12:00:01] E  Database        Connection refused  { host: 'localhost' }
+ *   [2026-03-15 12:00:02] W  Auth            Token expiring soon
+ *
+ * WTF level also prints the full stack trace.
+ */
+class PrettyFormatter {
+  /**
+   * @param {object} options
+   * @param {boolean} [options.timestamp=true]    — show timestamp
+   * @param {boolean} [options.tag=true]          — show tag/component name
+   * @param {boolean} [options.colour=true]       — ANSI colour (disable for pipes/files)
+   * @param {string}  [options.timestampFormat]   — 'iso' | 'short' (default: 'short')
+   */
+  constructor(options = {}) {
+    this.showTimestamp = options.timestamp !== false;
+    this.showTag       = options.tag       !== false;
+    this.colour        = options.colour    !== false;
+    this.tsFormat      = options.timestampFormat || 'short';
+  }
+
+  format(entry) {
+    const { level, tag, message, context, error } = entry;
+
+    const c    = this.colour ? LEVEL_COLOURS[level] : '';
+    const r    = this.colour ? RESET                : '';
+    const b    = this.colour ? BOLD                 : '';
+    const d    = this.colour ? '\x1b[2m'            : '';
+    const lvl  = LEVEL_TAGS[level] || '?';
+
+    const parts = [];
+
+    // Timestamp
+    if (this.showTimestamp) {
+      const ts = this._timestamp();
+      parts.push(`${d}[${ts}]${r}`);
+    }
+
+    // Level tag (single letter, coloured)
+    parts.push(`${c}${b}${lvl}${r}`);
+
+    // Component/tag
+    if (this.showTag && tag) {
+      const tagStr = tag.padEnd(18);
+      parts.push(`${b}${tagStr}${r}`);
+    }
+
+    // Message
+    parts.push(`${c}${message}${r}`);
+
+    // Context object
+    if (context !== undefined && context !== null) {
+      const ctx = typeof context === 'object'
+        ? JSON.stringify(context, null, 0)
+        : String(context);
+      parts.push(`${d}${ctx}${r}`);
+    }
+
+    let output = parts.join('  ');
+
+    // Error stack
+    if (error instanceof Error) {
+      output += `\n${d}${error.stack || error.message}${r}`;
+    }
+
+    // WTF: print big warning banner
+    if (level === 5) {
+      const banner = this.colour
+        ? `\x1b[35m\x1b[1m${'━'.repeat(60)}\x1b[0m`
+        : '━'.repeat(60);
+      output = `${banner}\n${output}\n${banner}`;
+    }
+
+    return output;
+  }
+
+  _timestamp() {
+    const now = new Date();
+    if (this.tsFormat === 'iso') return now.toISOString();
+    return now.toISOString().replace('T', ' ').slice(0, 19);
+  }
+}
+
+module.exports = PrettyFormatter;

package/src/logger/formatters/SimpleFormatter.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { LEVEL_NAMES } = require('../levels');
+
+/**
+ * SimpleFormatter
+ *
+ * Plain, no-colour text. Suitable for file output or any sink
+ * where ANSI codes would be noise.
+ *
+ * Output:
+ *   [2026-03-15 12:00:00] [INFO]  Auth: User logged in
+ *   [2026-03-15 12:00:01] [ERROR] DB: Query failed {"table":"users"}
+ */
+class SimpleFormatter {
+  format(entry) {
+    const { level, tag, message, context, error, timestamp } = entry;
+
+    const ts      = (timestamp || new Date().toISOString()).replace('T', ' ').slice(0, 23);
+    const lvlName = (LEVEL_NAMES[level] || String(level)).padEnd(7);
+    const tagPart = tag ? `${tag}: ` : '';
+
+    let line = `[${ts}] [${lvlName}] ${tagPart}${message}`;
+
+    if (context !== undefined && context !== null) {
+      line += ' ' + (typeof context === 'object' ? JSON.stringify(context) : String(context));
+    }
+
+    if (error instanceof Error) {
+      line += '\n  ' + (error.stack || error.message).replace(/\n/g, '\n  ');
+    }
+
+    return line;
+  }
+}
+
+module.exports = SimpleFormatter;

package/src/logger/index.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const Logger          = require('./Logger');
+const { LEVELS, LEVEL_NAMES } = require('./levels');
+const PrettyFormatter = require('./formatters/PrettyFormatter');
+const JsonFormatter   = require('./formatters/JsonFormatter');
+const SimpleFormatter = require('./formatters/SimpleFormatter');
+const ConsoleChannel  = require('./channels/ConsoleChannel');
+const FileChannel     = require('./channels/FileChannel');
+const { NullChannel, StackChannel } = require('./channels/index');
+
+/**
+ * Log
+ *
+ * The global logger singleton — the one you import everywhere.
+ *
+ *   const { Log } = require('millas');
+ *
+ *   Log.i('App booted');
+ *   Log.tag('UserService').d('Fetching user', { id: 5 });
+ *   Log.e('Payment', 'Stripe failed', error);
+ *   Log.wtf('Impossible state reached');
+ *
+ * Configured automatically by LogServiceProvider when you add it
+ * to your providers list. For manual setup:
+ *
+ *   Log.configure({
+ *     minLevel: LEVELS.INFO,
+ *     channel: new StackChannel([
+ *       new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *       new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.WARN }),
+ *     ]),
+ *   });
+ */
+const Log = new Logger();
+
+// Apply sensible defaults so Log works out-of-the-box before
+// LogServiceProvider runs (during framework boot, tests, etc.)
+Log.configure({
+  minLevel: process.env.NODE_ENV === 'production' ? LEVELS.INFO : LEVELS.DEBUG,
+  channel: new ConsoleChannel({
+    formatter: new PrettyFormatter({
+      colour: process.stdout.isTTY !== false,
+    }),
+  }),
+});
+
+module.exports = {
+  // The singleton you use everywhere
+  Log,
+
+  // The class (for constructing named loggers)
+  Logger,
+
+  // Level constants
+  LEVELS,
+  LEVEL_NAMES,
+
+  // Formatters
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+
+  // Channels
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+};

package/src/logger/levels.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Log levels — ordered by severity (lowest to highest).
+ *
+ * Inspired by Android's Timber / Log class:
+ *   VERBOSE  — extremely detailed; usually filtered out in production
+ *   DEBUG    — development diagnostics
+ *   INFO     — normal operational messages (default minimum in production)
+ *   WARN     — something unexpected but recoverable
+ *   ERROR    — something failed; needs attention
+ *   WTF      — "What a Terrible Failure" — should never happen; always logged
+ */
+const LEVELS = {
+  VERBOSE: 0,
+  DEBUG:   1,
+  INFO:    2,
+  WARN:    3,
+  ERROR:   4,
+  WTF:     5,
+};
+
+/** Reverse map: number → name */
+const LEVEL_NAMES = Object.fromEntries(
+  Object.entries(LEVELS).map(([k, v]) => [v, k])
+);
+
+/** Single-letter tags (like Android logcat) */
+const LEVEL_TAGS = {
+  0: 'V',
+  1: 'D',
+  2: 'I',
+  3: 'W',
+  4: 'E',
+  5: 'F', // Fatal / WTF
+};
+
+/** ANSI colour codes for each level */
+const LEVEL_COLOURS = {
+  0: '\x1b[90m',   // VERBOSE  — dark grey
+  1: '\x1b[36m',   // DEBUG    — cyan
+  2: '\x1b[32m',   // INFO     — green
+  3: '\x1b[33m',   // WARN     — yellow
+  4: '\x1b[31m',   // ERROR    — red
+  5: '\x1b[35m',   // WTF      — magenta
+};
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+
+module.exports = { LEVELS, LEVEL_NAMES, LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD, DIM };

package/src/middleware/LogMiddleware.js

@@ -5,53 +5,79 @@ const Middleware = require('./Middleware');
 /**
  * LogMiddleware
  *
- * Logs every incoming request and its response time.
+ * Django-style HTTP request logger.
+ * Uses the Millas Log singleton — output goes through your configured channels.
  *
- * Output format:
- *   [2026-03-14 12:00:00] GET /api/users 200 12ms
+ * Log levels per status:
+ *   2xx, 3xx  → INFO   (green)
+ *   4xx       → WARN   (yellow)
+ *   5xx       → ERROR  (red)
+ *   slow req  → WARN   (with slow=true in context)
  *
- * Register:
- *   middlewareRegistry.register('log', LogMiddleware);
+ * Output:
+ *   I  HTTP  GET /api/users 200 4ms
+ *   W  HTTP  POST /api/login 401 12ms
+ *   E  HTTP  GET /api/crash 500 3ms
+ *
+ * Usage (register as middleware):
+ *   app.use(new LogMiddleware().handle.bind(new LogMiddleware()));
+ *
+ * Or use Log.requestMiddleware() directly for more options.
  *
  * Options:
- *   silent  — suppress output (default: false)
- *   format  — 'dev' (coloured) | 'combined' (plain)
+ *   silent        — suppress all output (default: false)
+ *   includeQuery  — include query string in URL (default: false)
+ *   includeIp     — include client IP (default: true)
+ *   slowThreshold — warn if response > Nms (default: 1000)
+ *   skip          — function(req, res) => bool — skip matching routes
  */
 class LogMiddleware extends Middleware {
   constructor(options = {}) {
     super();
-    this.silent = options.silent || false;
-    this.format = options.format || 'dev';
+    this.silent        = options.silent        ?? false;
+    this.includeQuery  = options.includeQuery  ?? false;
+    this.includeIp     = options.includeIp     ?? true;
+    this.slowThreshold = options.slowThreshold ?? 1000;
+    this.skip          = options.skip          ?? null;
   }
 
   async handle(req, res, next) {
     if (this.silent) return next();
+    if (typeof this.skip === 'function' && this.skip(req, res)) return next();
+
+    // Lazy-require Log so this file loads even before LogServiceProvider runs
+    let Log;
+    try {
+      Log = require('../logger/index').Log;
+    } catch {
+      return next();
+    }
 
     const start = Date.now();
-    const { method, path: routePath, url } = req;
+    const { LEVELS } = require('../logger/levels');
 
     res.on('finish', () => {
       const ms     = Date.now() - start;
       const status = res.statusCode;
-      const ts     = new Date().toISOString().replace('T', ' ').slice(0, 19);
-
-      if (this.format === 'dev') {
-        const statusColor = status < 300 ? '\x1b[32m'
-          : status < 400 ? '\x1b[36m'
-          : status < 500 ? '\x1b[33m'
-          : '\x1b[31m';
-        const reset = '\x1b[0m';
-        const methodColor = '\x1b[1m';
-        console.log(
-          `  ${'\x1b[90m'}[${ts}]${reset} ` +
-          `${methodColor}${method.padEnd(7)}${reset} ` +
-          `${routePath || url} ` +
-          `${statusColor}${status}${reset} ` +
-          `${'\x1b[90m'}${ms}ms${reset}`
-        );
-      } else {
-        console.log(`[${ts}] ${method} ${routePath || url} ${status} ${ms}ms`);
+      const method = req.method;
+      let   url    = req.path || req.url || '/';
+
+      if (this.includeQuery && req.url && req.url.includes('?')) {
+        url = req.url;
       }
+
+      // Level based on status + response time
+      let level;
+      if      (status >= 500)          level = LEVELS.ERROR;
+      else if (status >= 400)          level = LEVELS.WARN;
+      else if (ms > this.slowThreshold) level = LEVELS.WARN;
+      else                             level = LEVELS.INFO;
+
+      const ctx = { status, ms };
+      if (this.includeIp) ctx.ip = req.ip || req.connection?.remoteAddress;
+      if (ms > this.slowThreshold) ctx.slow = true;
+
+      Log._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
     });
 
     next();

package/src/providers/LogServiceProvider.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const {
+  Log,
+  Logger,
+  LEVELS,
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+} = require('../logger/index');
+
+/**
+ * LogServiceProvider
+ *
+ * Reads config/logging.js and configures the Log singleton.
+ * Also registers Log and Logger in the DI container.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([LogServiceProvider, ...]);
+ *
+ * The provider is intentionally ordered first so every other provider
+ * can use Log during their boot() method.
+ *
+ * config/logging.js is optional — sensible defaults apply if absent.
+ */
+class LogServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Log',    Log);
+    container.instance('Logger', Logger);
+  }
+
+  async boot(container, app) {
+    let config = {};
+    try {
+      config = require(process.cwd() + '/config/logging');
+    } catch {
+      // No config — use defaults already set in logger/index.js
+      return;
+    }
+
+    const channels = this._buildChannels(config);
+
+    Log.configure({
+      minLevel:   this._resolveLevel(config.level ?? config.minLevel),
+      defaultTag: config.defaultTag || 'App',
+      channel:    channels.length === 1
+        ? channels[0]
+        : new StackChannel(channels),
+    });
+
+    Log.tag('Millas').i(`Logger configured — level: ${this._levelName(Log._minLevel)}, channels: ${channels.length}`);
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  _buildChannels(config) {
+    const channelDefs = config.channels || ['console'];
+    const built       = [];
+
+    for (const def of channelDefs) {
+      // String shorthand: 'console' | 'file' | 'null'
+      if (def === 'console' || def?.driver === 'console') {
+        built.push(this._buildConsole(def));
+      } else if (def === 'file' || def?.driver === 'file') {
+        built.push(this._buildFile(def));
+      } else if (def === 'null' || def?.driver === 'null') {
+        built.push(new NullChannel());
+      } else if (def && typeof def.write === 'function') {
+        // Already an instantiated channel — use directly
+        built.push(def);
+      }
+    }
+
+    // Always have at least a console channel
+    if (!built.length) built.push(this._buildConsole({}));
+
+    return built;
+  }
+
+  _buildConsole(opts = {}) {
+    const fmt = this._buildFormatter(opts.formatter || opts.format || 'pretty', opts);
+    return new ConsoleChannel({
+      formatter: fmt,
+      minLevel:  this._resolveLevel(opts.level ?? opts.minLevel),
+    });
+  }
+
+  _buildFile(opts = {}) {
+    const fmt = this._buildFormatter(opts.formatter || opts.format || 'simple', opts);
+    return new FileChannel({
+      path:      opts.path     || 'storage/logs',
+      prefix:    opts.prefix   || 'millas',
+      formatter: fmt,
+      minLevel:  this._resolveLevel(opts.level ?? opts.minLevel),
+      maxFiles:  opts.maxFiles ?? 30,
+    });
+  }
+
+  _buildFormatter(name, opts = {}) {
+    if (name && typeof name === 'object' && typeof name.format === 'function') {
+      return name; // already an instance
+    }
+    switch (String(name).toLowerCase()) {
+      case 'json':
+        return new JsonFormatter({ extra: opts.extra });
+      case 'simple':
+        return new SimpleFormatter();
+      case 'pretty':
+      default:
+        return new PrettyFormatter({
+          colour:           opts.colour !== false && process.stdout.isTTY !== false,
+          timestamp:        opts.timestamp !== false,
+          tag:              opts.tag !== false,
+          timestampFormat:  opts.timestampFormat || 'short',
+        });
+    }
+  }
+
+  _resolveLevel(level) {
+    if (level === undefined || level === null) {
+      return process.env.NODE_ENV === 'production' ? LEVELS.INFO : LEVELS.DEBUG;
+    }
+    if (typeof level === 'number') return level;
+    return LEVELS[String(level).toUpperCase()] ?? LEVELS.DEBUG;
+  }
+
+  _levelName(n) {
+    const names = ['VERBOSE','DEBUG','INFO','WARN','ERROR','WTF'];
+    return names[n] || String(n);
+  }
+}
+
+module.exports = LogServiceProvider;

package/src/scaffold/templates.js

@@ -66,8 +66,6 @@ storage/logs/*.log
 storage/uploads/*
 !storage/uploads/.gitkeep
 database/database.sqlite
-# Millas migration snapshot — auto-generated, do not commit
-.millas/
 `,
 
     // ─── millas.config.js ─────────────────────────────────────────
@@ -106,6 +104,7 @@ function resolveMillas() {
 const {
   Application,
   Admin,
+  LogServiceProvider,
   CacheServiceProvider,
   StorageServiceProvider,
   MailServiceProvider,
@@ -124,6 +123,7 @@ const app = new Application(expressApp);
 
 // ── Register service providers ──────────────────────────────────
 app.providers([
+  LogServiceProvider,       // first — so Log works in all other providers
   CacheServiceProvider,
   StorageServiceProvider,
   MailServiceProvider,
@@ -198,6 +198,38 @@ module.exports = function (Route) {
 
   });
 };
+`,
+
+    // ─── config/logging.js ────────────────────────────────────────
+    'config/logging.js': `'use strict';
+
+/**
+ * Logging Configuration
+ *
+ * Levels (lowest → highest): verbose | debug | info | warn | error | wtf
+ * Channels: 'console' | 'file' | 'null'
+ * Formats:  'pretty' (coloured) | 'simple' (plain text) | 'json' (structured)
+ */
+module.exports = {
+  level: process.env.LOG_LEVEL || (process.env.NODE_ENV === 'production' ? 'info' : 'debug'),
+
+  defaultTag: process.env.APP_NAME || 'App',
+
+  channels: [
+    {
+      driver: 'console',
+      format: 'pretty',
+    },
+    {
+      driver:   'file',
+      format:   'simple',
+      path:     'storage/logs',
+      prefix:   '${projectName}',
+      level:    'warn',
+      maxFiles: 30,
+    },
+  ],
+};
 `,
 
     // ─── config/app.js ────────────────────────────────────────────
@@ -358,37 +390,17 @@ millas make:controller UserController
 
 # Generate a model
 millas make:model User
-\`\`\`
 
-## Database Migrations (Django-style)
-
-Millas handles migrations automatically — you only edit your model files.
-
-\`\`\`bash
-# 1. Edit app/models/User.js — add, remove, or change fields
-# 2. Generate migration files from your changes
-millas makemigrations
-
-# 3. Apply pending migrations to the database
+# Run migrations
 millas migrate
 \`\`\`
 
-Other migration commands:
-
-\`\`\`bash
-millas migrate:status     # Show which migrations have run
-millas migrate:rollback   # Undo the last batch
-millas migrate:fresh      # Drop everything and re-run all migrations
-millas migrate:reset      # Roll back all migrations
-millas migrate:refresh    # Reset + re-run (like fresh but using down() methods)
-\`\`\`
-
 ## Project Structure
 
 \`\`\`
 app/
   controllers/    # HTTP controllers
-  models/         # ORM models  ← only file you edit for schema changes
+  models/         # ORM models
   services/       # Business logic
   middleware/     # HTTP middleware
   jobs/           # Background jobs
@@ -396,14 +408,13 @@ bootstrap/
   app.js          # Application entry point
 config/           # Configuration files
 database/
-  migrations/     # Auto-generated — do not edit by hand
+  migrations/     # Database migrations
   seeders/        # Database seeders
 routes/
   web.js          # Web routes
   api.js          # API routes
 storage/          # Logs, uploads
 providers/        # Service providers
-.millas/          # Migration snapshot (gitignored)
 \`\`\`
 `,
   };