millas 0.2.5 → 0.2.7

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)
 \`\`\`
 `,
   };