millas 0.2.12-beta-1 → 0.2.13-beta

package/src/i18n/defaults.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Millas framework default translatable strings.
+ *
+ * These are the strings used internally by Millas — validation messages,
+ * auth errors, admin panel labels, migration prompts, etc.
+ *
+ * When a developer runs `millas lang:publish sw --defaults`, these keys
+ * are merged into their locale file alongside their own app strings.
+ *
+ * Organised by module so translators know the context.
+ * All values are the English source text — same key = same value for 'en'.
+ *
+ * Format:
+ *   'key':              'English source text'   — simple string
+ *   'key':              ['singular', 'plural']  — plural form
+ *   'context|key':      'English source text'   — contextual
+ */
+module.exports = {
+
+  // ── Validation ─────────────────────────────────────────────────────────
+  'This field is required.':                        'This field is required.',
+  'Maximum {max} characters allowed.':              'Maximum {max} characters allowed.',
+  'Must be a whole number.':                        'Must be a whole number.',
+  'Must be a number.':                              'Must be a number.',
+  'Must be a valid email address.':                 'Must be a valid email address.',
+  'Must be a valid URL.':                           'Must be a valid URL.',
+  'Must be a valid date (YYYY-MM-DD).':             'Must be a valid date (YYYY-MM-DD).',
+  'Must be valid JSON.':                            'Must be valid JSON.',
+  'Must be a valid UUID.':                          'Must be a valid UUID.',
+  'Please select a value.':                         'Please select a value.',
+  'Please select a related record.':                'Please select a related record.',
+  'Invalid value. Must be one of: {values}':        'Invalid value. Must be one of: {values}',
+  'Password must be at least 8 characters.':        'Password must be at least 8 characters.',
+
+  // ── Auth ───────────────────────────────────────────────────────────────
+  'Email is required':                              'Email is required',
+  'Password is required':                           'Password is required',
+  'Invalid email or password':                      'Invalid email or password',
+  'Your account has been deactivated':              'Your account has been deactivated',
+  'Email already in use':                           'Email already in use',
+  'Passwords do not match':                         'Passwords do not match',
+  'Token has expired':                              'Token has expired',
+  'Invalid token':                                  'Invalid token',
+  'You are not authorized to perform this action':  'You are not authorized to perform this action',
+
+  // ── HTTP errors ────────────────────────────────────────────────────────
+  'Not Found':                                      'Not Found',
+  'Unauthorized':                                   'Unauthorized',
+  'Forbidden':                                      'Forbidden',
+  'Unprocessable Entity':                           'Unprocessable Entity',
+  'Internal Server Error':                          'Internal Server Error',
+  'Too Many Requests':                              'Too Many Requests',
+  '{model} #{id} not found':                        '{model} #{id} not found',
+
+  // ── Pagination ─────────────────────────────────────────────────────────
+  'Showing {from} to {to} of {total} results':      'Showing {from} to {to} of {total} results',
+  'Previous':                                       'Previous',
+  'Next':                                           'Next',
+  'Page {page} of {total}':                         'Page {page} of {total}',
+
+  // ── CRUD ───────────────────────────────────────────────────────────────
+  '{model} created successfully':                   '{model} created successfully',
+  '{model} updated successfully':                   '{model} updated successfully',
+  '{model} deleted':                                '{model} deleted',
+  'No records found':                               'No records found',
+  'Record not found':                               'Record not found',
+
+  // ── Plural CRUD ────────────────────────────────────────────────────────
+  '{count} record deleted':               ['{count} record deleted',    '{count} records deleted'],
+  '{count} record updated':               ['{count} record updated',    '{count} records updated'],
+
+  // ── Admin panel ────────────────────────────────────────────────────────
+  'Dashboard':                                      'Dashboard',
+  'Search':                                         'Search',
+  'Filters':                                        'Filters',
+  'Actions':                                        'Actions',
+  'Export CSV':                                     'Export CSV',
+  'Export JSON':                                    'Export JSON',
+  'Save':                                           'Save',
+  'Save and continue editing':                      'Save and continue editing',
+  'Save and add another':                           'Save and add another',
+  'Delete':                                         'Delete',
+  'Cancel':                                         'Cancel',
+  'Edit':                                           'Edit',
+  'Add {model}':                                    'Add {model}',
+  'Change {model}':                                 'Change {model}',
+  'Delete {model}':                                 'Delete {model}',
+  'Are you sure you want to delete {label}?':       'Are you sure you want to delete {label}?',
+  'This action cannot be undone.':                  'This action cannot be undone.',
+  'No {model} yet':                                 'No {model} yet',
+  'Select all':                                     'Select all',
+  'Deselect all':                                   'Deselect all',
+
+  // ── Admin status badges (contextual) ───────────────────────────────────
+  'status|active':                                  'Active',
+  'status|inactive':                                'Inactive',
+  'status|pending':                                 'Pending',
+  'status|approved':                                'Approved',
+  'status|rejected':                                'Rejected',
+  'status|draft':                                   'Draft',
+  'status|published':                               'Published',
+
+  // ── Admin login ────────────────────────────────────────────────────────
+  'Sign in to your account':                        'Sign in to your account',
+  'Email address':                                  'Email address',
+  'Password':                                       'Password',
+  'Remember me':                                    'Remember me',
+  'Sign in':                                        'Sign in',
+  'Sign out':                                       'Sign out',
+  'You have been logged out.':                      'You have been logged out.',
+
+  // ── Migration prompts ──────────────────────────────────────────────────
+  'No changes detected.':                           'No changes detected.',
+  'Migrations generated:':                          'Migrations generated:',
+  'Run: millas migrate   to apply.':                'Run: millas migrate   to apply.',
+
+  // ── Queue ──────────────────────────────────────────────────────────────
+  'Job failed: {message}':                          'Job failed: {message}',
+  'Job completed: {job}':                           'Job completed: {job}',
+};

package/src/i18n/index.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const Translator = require('./Translator');
+
+/**
+ * Trans — global translation singleton + shorthand helpers.
+ *
+ * This is the object you import in controllers, models, views, and commands.
+ * It wraps the Translator instance with the Django-style shorthand functions.
+ *
+ * ── Import styles ──────────────────────────────────────────────────────────
+ *
+ *   // Named destructuring (recommended)
+ *   const { __, _n, _p, _f } = require('millas/src/i18n');
+ *
+ *   // Full facade for locale control
+ *   const { Trans } = require('millas/src/i18n');
+ *   Trans.setLocale('sw');
+ *
+ * ── API ────────────────────────────────────────────────────────────────────
+ *
+ *   __('Hello')
+ *   → 'Habari'   (when locale=sw)
+ *   → 'Hello'    (when locale=en or no translation found)
+ *
+ *   _n('You have %d message', 'You have %d messages', 3)
+ *   → 'Una ujumbe 3'
+ *
+ *   _p('menu', 'File')
+ *   → 'Faili'   (contextual — same word, different contexts)
+ *
+ *   _f('Welcome, {name}!', { name: 'Alice' })
+ *   → 'Karibu, Alice!'
+ *
+ *   _f('Hello %s, you have %d items', 'Alice', 5)
+ *   → 'Habari Alice, una vitu 5'
+ *
+ *   _fn('You have %d item', 'You have %d items', 3)
+ *   → 'Una vitu 3'
+ *
+ * ── In templates (Nunjucks) ────────────────────────────────────────────────
+ *
+ *   Add the filters via I18nServiceProvider (done automatically):
+ *
+ *   {{ 'Hello' | __ }}
+ *   {{ 'You have %d messages' | _n(count) }}
+ *   {{ 'Welcome, {name}!' | _f({ name: user.name }) }}
+ *
+ * ── In CLI commands ────────────────────────────────────────────────────────
+ *
+ *   const { __ } = require('millas/src/i18n');
+ *   console.log(__('Migrations applied successfully.'));
+ */
+
+// ── Singleton Translator instance ────────────────────────────────────────────
+const Trans = new Translator();
+
+// ── Shorthand functions ───────────────────────────────────────────────────────
+
+/**
+ * gettext — translate a string.
+ *
+ *   __('Hello')
+ *   __('Hello', 'sw')    // explicit locale override
+ *
+ * @param {string} key
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function __(key, locale) {
+  return Trans.translate(key, locale);
+}
+
+/**
+ * ngettext — singular/plural translation.
+ *
+ *   _n('You have %d message', 'You have %d messages', count)
+ *
+ * Note: this does NOT interpolate %d — call _fn() if you also need
+ * the count substituted into the string.
+ *
+ * @param {string} singular
+ * @param {string} plural
+ * @param {number} count
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function _n(singular, plural, count, locale) {
+  return Trans.ngettext(singular, plural, count, locale);
+}
+
+/**
+ * pgettext — contextual translation.
+ *
+ *   _p('menu', 'File')     // the menu item "File"
+ *   _p('action', 'File')   // the action "to file something"
+ *
+ * @param {string} context
+ * @param {string} key
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function _p(context, key, locale) {
+  return Trans.pgettext(context, key, locale);
+}
+
+/**
+ * format — translate + interpolate named or positional variables.
+ *
+ *   _f('Welcome, {name}!', { name: 'Alice' })
+ *   _f('Hello %s, you have %d items', 'Alice', 5)
+ *
+ * @param {string} key
+ * @param {...*}   args
+ * @returns {string}
+ */
+function _f(key, ...args) {
+  return Trans.format(key, ...args);
+}
+
+/**
+ * nformat — plural translation + interpolation.
+ *
+ *   _fn('You have %d item', 'You have %d items', count)
+ *   // → 'You have 3 items'  (count is auto-interpolated as first %d)
+ *
+ * @param {string} singular
+ * @param {string} plural
+ * @param {number} count
+ * @param {...*}   args  — additional interpolation values after count
+ * @returns {string}
+ */
+function _fn(singular, plural, count, ...args) {
+  return Trans.nformat(singular, plural, count, ...args);
+}
+
+/**
+ * lazy — returns a lazy-evaluated translation proxy.
+ *
+ * Useful when the translation needs to be stored before the locale is set
+ * (e.g. in class-level constants, model field labels).
+ *
+ *   const label = lazy__('Email address');
+ *   // label() → 'Anwani ya barua pepe'   (evaluated at call time)
+ *
+ * @param {string} key
+ * @returns {Function}
+ */
+function lazy__(key) {
+  return () => Trans.translate(key);
+}
+
+module.exports = {
+  // Singleton for locale control + advanced usage
+  Trans,
+
+  // Shorthand functions
+  __,
+  _n,
+  _p,
+  _f,
+  _fn,
+  lazy__,
+};

package/src/i18n/locales/en.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * English (en) — source language catalogue.
+ *
+ * For the source language this file acts as documentation:
+ * it lists every translatable string in the application.
+ * Values are the same as keys — no actual translation needed.
+ *
+ * Other locale files only need to include keys where the translation
+ * differs. Missing keys fall back to this file, then to the raw key.
+ *
+ * ── Auth ──────────────────────────────────────────────────────────────────
+ */
+module.exports = {
+
+  // ── Auth / validation ────────────────────────────────────────────────────
+  'Email is required':                      'Email is required',
+  'Password is required':                   'Password is required',
+  'Invalid email or password':              'Invalid email or password',
+  'Your account has been deactivated':      'Your account has been deactivated',
+  'Email already in use':                   'Email already in use',
+  'Password must be at least 8 characters': 'Password must be at least 8 characters',
+  'Passwords do not match':                 'Passwords do not match',
+
+  // ── CRUD messages ────────────────────────────────────────────────────────
+  '%s created successfully':                '%s created successfully',
+  '%s updated successfully':                '%s updated successfully',
+  '%s deleted':                             '%s deleted',
+  'No records found':                       'No records found',
+  'Record not found':                       'Record not found',
+
+  // ── Pagination ───────────────────────────────────────────────────────────
+  'Showing %d to %d of %d results':         'Showing %d to %d of %d results',
+  'Previous':                               'Previous',
+  'Next':                                   'Next',
+
+  // ── Plural examples ──────────────────────────────────────────────────────
+  // Array format: [singular_form, plural_form, ...]
+  'You have %d message':                    ['You have %d message',  'You have %d messages'],
+  '%d item selected':                       ['%d item selected',     '%d items selected'],
+  '%d record deleted':                      ['%d record deleted',    '%d records deleted'],
+
+  // ── Contextual examples (context|key) ────────────────────────────────────
+  'menu|File':                              'File',
+  'menu|Edit':                              'Edit',
+  'status|active':                          'Active',
+  'status|inactive':                        'Inactive',
+  'status|pending':                         'Pending',
+
+  // ── Named interpolation examples ─────────────────────────────────────────
+  'Welcome, {name}!':                       'Welcome, {name}!',
+  'Hello, {name}. You have {count} notifications.':
+    'Hello, {name}. You have {count} notifications.',
+};

package/src/i18n/locales/sw.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Swahili (sw) translation catalogue.
+ *
+ * Only include keys where the translation differs from the source.
+ * Missing keys automatically fall back to the fallback locale (en).
+ */
+module.exports = {
+
+  // ── Auth / validation ────────────────────────────────────────────────────
+  'Email is required':                      'Barua pepe inahitajika',
+  'Password is required':                   'Nywila inahitajika',
+  'Invalid email or password':              'Barua pepe au nywila si sahihi',
+  'Your account has been deactivated':      'Akaunti yako imezimwa',
+  'Email already in use':                   'Barua pepe hiyo tayari inatumika',
+  'Password must be at least 8 characters': 'Nywila lazima iwe na herufi angalau 8',
+  'Passwords do not match':                 'Nywila hazifanani',
+
+  // ── CRUD messages ────────────────────────────────────────────────────────
+  '%s created successfully':                '%s imeundwa kikamilifu',
+  '%s updated successfully':                '%s imesasishwa kikamilifu',
+  '%s deleted':                             '%s imefutwa',
+  'No records found':                       'Hakuna rekodi zilizopatikana',
+  'Record not found':                       'Rekodi haijapatikana',
+
+  // ── Pagination ───────────────────────────────────────────────────────────
+  'Showing %d to %d of %d results':         'Inaonyesha %d hadi %d kati ya %d matokeo',
+  'Previous':                               'Iliyotangulia',
+  'Next':                                   'Inayofuata',
+
+  // ── Plural forms (Swahili uses same form for all counts) ─────────────────
+  'You have %d message':                    ['Una ujumbe %d', 'Una ujumbe %d'],
+  '%d item selected':                       ['%d kipengele kimechaguliwa', '%d vipengele vimechaguliwa'],
+  '%d record deleted':                      ['Rekodi %d imefutwa', 'Rekodi %d zimefutwa'],
+
+  // ── Contextual ───────────────────────────────────────────────────────────
+  'menu|File':      'Faili',
+  'menu|Edit':      'Hariri',
+  'status|active':  'Amilifu',
+  'status|inactive':'Haifanyi kazi',
+  'status|pending': 'Inasubiri',
+
+  // ── Named interpolation ──────────────────────────────────────────────────
+  'Welcome, {name}!':  'Karibu, {name}!',
+  'Hello, {name}. You have {count} notifications.':
+    'Habari {name}. Una arifa {count}.',
+};

package/src/logger/LogRedactor.js

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * LogRedactor
+ *
+ * Scrubs sensitive field values from log context objects before they
+ * are serialised and written to any log channel.
+ *
+ * ── Why this matters ─────────────────────────────────────────────────────────
+ *
+ *   Log.d('Auth', 'Login', { email, password });       // password logged ✗
+ *   Log.d('AI',   'Config', this._config);             // API keys logged ✗
+ *   Log.d('HTTP', 'Request', req.body);                // form fields logged ✗
+ *
+ *   With redaction enabled (default):
+ *   Log.d('Auth', 'Login', { email, password });
+ *   → { email: 'alice@example.com', password: '[REDACTED]' }
+ *
+ * ── Default sensitive field names ────────────────────────────────────────────
+ *
+ *   password, passwd, secret, token, apikey, api_key, authorization,
+ *   cookie, access_token, refresh_token, private_key, private, credential,
+ *   ssn, credit_card, card_number, cvv, pin
+ *
+ *   Matching is case-insensitive and substring-based:
+ *     'userPassword' matches 'password'
+ *     'X-API-Key'    matches 'apikey'
+ *     'AUTHORIZATION' matches 'authorization'
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ *
+ *   // Add custom sensitive field names (globally):
+ *   LogRedactor.addSensitiveKeys(['mpesa_pin', 'stk_passkey', 'webhook_secret']);
+ *
+ *   // Replace the entire list:
+ *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_secret']);
+ *
+ *   // Change the redaction placeholder:
+ *   LogRedactor.setPlaceholder('***');
+ *
+ *   // Disable redaction entirely (not recommended for production):
+ *   LogRedactor.disable();
+ *
+ * ── Integration ───────────────────────────────────────────────────────────────
+ *
+ *   Redaction is applied automatically inside every formatter's format() call.
+ *   No action needed — it is on by default.
+ */
+
+// ── Default sensitive key fragments ───────────────────────────────────────────
+
+const DEFAULT_KEYS = [
+  'password', 'passwd', 'pass',
+  'secret',
+  'token',
+  'apikey', 'api_key',
+  'authorization', 'auth',
+  'cookie',
+  'access_token', 'accesstoken',
+  'refresh_token', 'refreshtoken',
+  'private_key', 'privatekey', 'private',
+  'credential', 'credentials',
+  'ssn',
+  'credit_card', 'creditcard', 'card_number', 'cardnumber',
+  'cvv', 'cvc',
+  'pin',
+  'passphrase',
+  'webhook_secret', 'signing_secret',
+];
+
+// ── Module-level state ────────────────────────────────────────────────────────
+
+let _sensitiveKeys  = [...DEFAULT_KEYS];
+let _placeholder    = '[REDACTED]';
+let _enabled        = true;
+let _cachedLower    = null;  // lazily built lowercased copy
+
+function _getLower() {
+  if (!_cachedLower) _cachedLower = _sensitiveKeys.map(k => k.toLowerCase());
+  return _cachedLower;
+}
+
+function _invalidateCache() {
+  _cachedLower = null;
+}
+
+// ── Core redaction ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a key name contains any sensitive fragment.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isSensitiveKey(key) {
+  const lower  = String(key).toLowerCase().replace(/[-_\s]/g, '');
+  const frags  = _getLower().map(k => k.replace(/[-_\s]/g, ''));
+  return frags.some(frag => lower.includes(frag));
+}
+
+/**
+ * Redact sensitive values from an object (shallow or deep).
+ * Returns a new object — never mutates the original.
+ *
+ * Handles:
+ *   - Plain objects (nested recursively up to depth 10)
+ *   - Arrays (each element redacted)
+ *   - Primitives (returned as-is unless the key is sensitive)
+ *   - Circular references (detected and replaced with '[Circular]')
+ *
+ * @param {*}      value    — the context value to redact
+ * @param {number} [depth]  — internal recursion counter
+ * @param {Set}    [seen]   — internal circular reference tracker
+ * @returns {*}
+ */
+function redact(value, depth = 0, seen = new Set()) {
+  if (!_enabled) return value;
+
+  // Depth guard — don't recurse into deeply nested structures
+  if (depth > 10) return value;
+
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+
+  // Circular reference guard
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    const result = value.map(item => redact(item, depth + 1, seen));
+    seen.delete(value);
+    return result;
+  }
+
+  const result = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (isSensitiveKey(k)) {
+      result[k] = _placeholder;
+    } else if (v !== null && typeof v === 'object') {
+      result[k] = redact(v, depth + 1, seen);
+    } else {
+      result[k] = v;
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+
+// ── LogRedactor class ─────────────────────────────────────────────────────────
+
+class LogRedactor {
+  /**
+   * The default list of sensitive key fragments.
+   * Useful when callers want to extend it:
+   *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_key']);
+   */
+  static get DEFAULT_KEYS() { return [...DEFAULT_KEYS]; }
+
+  /**
+   * Redact sensitive fields from a log context value.
+   * Non-objects are returned unchanged.
+   *
+   * @param {*} context
+   * @returns {*}
+   */
+  static redact(context) {
+    if (!_enabled) return context;
+    if (context === null || context === undefined) return context;
+    if (typeof context !== 'object') return context;
+    return redact(context);
+  }
+
+  /**
+   * Add extra sensitive key fragments to the global list.
+   *
+   *   LogRedactor.addSensitiveKeys(['mpesa_pin', 'stk_passkey']);
+   *
+   * @param {string[]} keys
+   */
+  static addSensitiveKeys(keys) {
+    _sensitiveKeys = [...new Set([..._sensitiveKeys, ...keys.map(k => k.toLowerCase())])];
+    _invalidateCache();
+  }
+
+  /**
+   * Replace the entire sensitive key list.
+   *
+   *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_secret']);
+   *
+   * @param {string[]} keys
+   */
+  static setSensitiveKeys(keys) {
+    _sensitiveKeys = keys.map(k => k.toLowerCase());
+    _invalidateCache();
+  }
+
+  /**
+   * Get a copy of the current sensitive key list.
+   *
+   * @returns {string[]}
+   */
+  static getSensitiveKeys() {
+    return [..._sensitiveKeys];
+  }
+
+  /**
+   * Change the redaction placeholder string.
+   *   LogRedactor.setPlaceholder('***');
+   *
+   * @param {string} placeholder
+   */
+  static setPlaceholder(placeholder) {
+    _placeholder = String(placeholder);
+  }
+
+  /**
+   * Enable redaction (default).
+   */
+  static enable() {
+    _enabled = true;
+  }
+
+  /**
+   * Disable redaction. Use only in test environments where you need
+   * to inspect exact log context values.
+   */
+  static disable() {
+    _enabled = false;
+  }
+
+  /**
+   * Whether redaction is currently enabled.
+   */
+  static get enabled() { return _enabled; }
+
+  /**
+   * Check if a specific key would be redacted.
+   *
+   *   LogRedactor.isSensitive('userPassword')  // true
+   *   LogRedactor.isSensitive('userId')        // false
+   */
+  static isSensitive(key) {
+    return isSensitiveKey(key);
+  }
+}
+
+module.exports = { LogRedactor, redact, isSensitiveKey };

package/src/logger/Logger.js

@@ -181,7 +181,7 @@ class Logger {
           ctx.slow = true;
         }
 
-        self._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
+        self._log(level, `HTTP [${method}]`, `${url} ${status} ${ms}ms`);
       });
 
       next();