millas 0.2.12-beta-1 → 0.2.13

package/src/process/Process.js

@@ -0,0 +1,333 @@
+'use strict';
+
+const { spawn, execSync } = require('child_process');
+
+// ── ProcessResult ─────────────────────────────────────────────────────────────
+
+class ProcessResult {
+  constructor({ exitCode, stdout, stderr, command }) {
+    this._exitCode = exitCode;
+    this._stdout   = stdout   || '';
+    this._stderr   = stderr   || '';
+    this._command  = command  || '';
+  }
+
+  /** Raw stdout string. */
+  output()      { return this._stdout; }
+
+  /** Raw stderr string. */
+  errorOutput() { return this._stderr; }
+
+  /** Exit code. */
+  exitCode()    { return this._exitCode; }
+
+  /** True if exit code is 0. */
+  get successful() { return this._exitCode === 0; }
+
+  /** True if exit code is not 0. */
+  get failed()     { return this._exitCode !== 0; }
+
+  /** Throw ProcessFailedException if the process failed. */
+  throw() {
+    if (this.failed) throw new ProcessFailedException(this);
+    return this;
+  }
+
+  /** Alias for throw(). */
+  throwIfFailed() { return this.throw(); }
+
+  toString() { return this._stdout; }
+}
+
+// ── ProcessFailedException ────────────────────────────────────────────────────
+
+class ProcessFailedException extends Error {
+  constructor(result) {
+    super(
+      `Process "${result._command}" failed with exit code ${result._exitCode}.\n` +
+      (result._stderr ? `STDERR: ${result._stderr.trim()}` : '')
+    );
+    this.name   = 'ProcessFailedException';
+    this.result = result;
+  }
+}
+
+// ── PendingProcess ────────────────────────────────────────────────────────────
+
+class PendingProcess {
+  constructor() {
+    this._cwd         = process.cwd();
+    this._env         = null;
+    this._timeout     = 0;
+    this._input       = null;
+    this._quietly     = false;
+    this._shell       = false;
+    this._throwOnFail = false;
+    this._onOutput    = null;
+    this._onError     = null;
+  }
+
+  // ── Builder ────────────────────────────────────────────────────────────────
+
+  /**
+   * Set working directory.
+   *   Process.path('/var/www').run('ls -la')
+   */
+  path(dir) { this._cwd = dir; return this; }
+
+  /**
+   * Set environment variables, merged with parent env by default.
+   * Pass inherit=false to use only the provided vars.
+   *   Process.env({ NODE_ENV: 'production' }).run('node server.js')
+   */
+  env(vars, inherit = true) {
+    this._env = inherit ? { ...process.env, ...vars } : vars;
+    return this;
+  }
+
+  /**
+   * Timeout in seconds. Kills the process if exceeded.
+   *   Process.timeout(30).run('npm install')
+   */
+  timeout(seconds) { this._timeout = seconds * 1000; return this; }
+
+  /**
+   * Pipe data to stdin.
+   *   Process.input('hello').run('cat')
+   */
+  input(data) { this._input = data; return this; }
+
+  /**
+   * Suppress stdout/stderr passthrough to parent process.
+   * Output is still captured on ProcessResult.
+   */
+  quietly() { this._quietly = true; return this; }
+
+  /**
+   * Run through /bin/sh — enables pipes, &&, ||, globs.
+   *   Process.shell().run('ls | grep .js && echo done')
+   */
+  shell() { this._shell = true; return this; }
+
+  /**
+   * Throw ProcessFailedException automatically on non-zero exit.
+   *   await Process.throwOnFailure().run('npm test')
+   */
+  throwOnFailure() { this._throwOnFail = true; return this; }
+
+  /**
+   * Register a line-by-line callback for stdout.
+   * Called for each newline-delimited line as the process runs.
+   * Can be combined with .run() — no need to use .pipe().
+   *
+   *   await Process
+   *     .onOutput(line => console.log('[OUT]', line))
+   *     .onError(line  => console.error('[ERR]', line))
+   *     .run('npm test');
+   */
+  onOutput(fn) { this._onOutput = fn; return this; }
+
+  /**
+   * Register a line-by-line callback for stderr.
+   *   .onError(line => logger.error(line))
+   */
+  onError(fn) { this._onError = fn; return this; }
+
+  // ── Execution ──────────────────────────────────────────────────────────────
+
+  /**
+   * Run asynchronously. Returns Promise<ProcessResult>.
+   *
+   *   const result = await Process.run('node --version');
+   *   const result = await Process.path('/app').timeout(60).quietly().run('npm ci');
+   */
+  run(command) {
+    return new Promise((resolve, reject) => {
+      const { cmd, args } = this._parse(command);
+      const child = spawn(cmd, args, {
+        cwd:   this._cwd,
+        env:   this._env || process.env,
+        shell: this._shell,
+        ...(this._timeout ? { timeout: this._timeout } : {}),
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      if (this._input !== null) {
+        child.stdin.write(String(this._input));
+        child.stdin.end();
+      }
+
+      let _outBuf = '';
+      let _errBuf = '';
+
+      const _flushLines = (buf, cb) => {
+        const lines = buf.split('\n');
+        buf = lines.pop();
+        lines.forEach(line => cb && cb(line));
+        return buf;
+      };
+
+      child.stdout.on('data', chunk => {
+        stdout += chunk;
+        if (!this._quietly) process.stdout.write(chunk);
+        if (this._onOutput) _outBuf = _flushLines(_outBuf + chunk, this._onOutput);
+      });
+      child.stderr.on('data', chunk => {
+        stderr += chunk;
+        if (!this._quietly) process.stderr.write(chunk);
+        if (this._onError) _errBuf = _flushLines(_errBuf + chunk, this._onError);
+      });
+
+      child.on('error', reject);
+      child.on('close', code => {
+        if (_outBuf && this._onOutput) this._onOutput(_outBuf);
+        if (_errBuf && this._onError)  this._onError(_errBuf);
+        const result = new ProcessResult({ exitCode: code ?? 1, stdout, stderr, command });
+        if (this._throwOnFail && result.failed) return reject(new ProcessFailedException(result));
+        resolve(result);
+      });
+    });
+  }
+
+  /**
+   * Stream output line-by-line in real-time via callbacks.
+   * Returns Promise<ProcessResult>.
+   *
+   *   await Process.pipe('npm install', {
+   *     stdout: line => console.log('[out]', line),
+   *     stderr: line => console.error('[err]', line),
+   *   });
+   */
+  pipe(command, { stdout: onOut, stderr: onErr } = {}) {
+    return new Promise((resolve, reject) => {
+      const { cmd, args } = this._parse(command);
+      const child = spawn(cmd, args, {
+        cwd:   this._cwd,
+        env:   this._env || process.env,
+        shell: this._shell,
+      });
+
+      let outBuf = '', errBuf = '', fullOut = '', fullErr = '';
+
+      const flush = (buf, cb) => {
+        const lines = buf.split('\n');
+        const rem   = lines.pop();
+        lines.forEach(l => cb && cb(l));
+        return rem;
+      };
+
+      child.stdout.on('data', chunk => {
+        fullOut += chunk; outBuf += chunk;
+        outBuf = flush(outBuf, onOut);
+        if (!this._quietly) process.stdout.write(chunk);
+      });
+      child.stderr.on('data', chunk => {
+        fullErr += chunk; errBuf += chunk;
+        errBuf = flush(errBuf, onErr);
+        if (!this._quietly) process.stderr.write(chunk);
+      });
+
+      child.on('error', reject);
+      child.on('close', code => {
+        if (outBuf) onOut && onOut(outBuf);
+        if (errBuf) onErr && onErr(errBuf);
+        const result = new ProcessResult({ exitCode: code ?? 1, stdout: fullOut, stderr: fullErr, command });
+        if (this._throwOnFail && result.failed) return reject(new ProcessFailedException(result));
+        resolve(result);
+      });
+    });
+  }
+
+  /**
+   * Run synchronously (blocking). Returns ProcessResult directly.
+   *
+   *   const result = Process.quietly().runSync('node --version');
+   */
+  runSync(command) {
+    try {
+      const out = execSync(command, {
+        cwd:     this._cwd,
+        env:     this._env || process.env,
+        timeout: this._timeout || undefined,
+        input:   this._input   !== null ? String(this._input) : undefined,
+        stdio:   'pipe',
+      });
+      const result = new ProcessResult({ exitCode: 0, stdout: out.toString(), stderr: '', command });
+      if (!this._quietly) process.stdout.write(out);
+      return result;
+    } catch (err) {
+      const result = new ProcessResult({
+        exitCode: err.status ?? 1,
+        stdout:   err.stdout?.toString() || '',
+        stderr:   err.stderr?.toString() || err.message || '',
+        command,
+      });
+      if (this._throwOnFail) throw new ProcessFailedException(result);
+      return result;
+    }
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  _parse(command) {
+    if (this._shell) return { cmd: command, args: [] };
+    const parts = command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+    const cmd   = parts[0];
+    const args  = parts.slice(1).map(a => a.replace(/^["']|["']$/g, ''));
+    return { cmd, args };
+  }
+}
+
+// ── ProcessPool ───────────────────────────────────────────────────────────────
+
+class ProcessPool {
+  async start(callback) {
+    const factory = new PendingProcess();
+    const tasks   = callback(factory) || [];
+    return Promise.all(tasks);
+  }
+}
+
+// ── ProcessManager ────────────────────────────────────────────────────────────
+
+class ProcessManager {
+  // Shorthand — execute immediately
+  run(command)                 { return new PendingProcess().run(command); }
+  runSync(command)             { return new PendingProcess().runSync(command); }
+  pipe(command, handlers)      { return new PendingProcess().pipe(command, handlers); }
+  onOutput(fn)                 { return new PendingProcess().onOutput(fn); }
+  onError(fn)                  { return new PendingProcess().onError(fn); }
+
+  // Builder starters — return PendingProcess for chaining
+  path(dir)                    { return new PendingProcess().path(dir); }
+  env(vars, inherit)           { return new PendingProcess().env(vars, inherit); }
+  timeout(seconds)             { return new PendingProcess().timeout(seconds); }
+  input(data)                  { return new PendingProcess().input(data); }
+  quietly()                    { return new PendingProcess().quietly(); }
+  shell()                      { return new PendingProcess().shell(); }
+  throwOnFailure()             { return new PendingProcess().throwOnFailure(); }
+
+  /**
+   * Run multiple processes concurrently.
+   *
+   *   const [lint, test, build] = await Process.pool(pool => [
+   *     pool.quietly().run('npm run lint'),
+   *     pool.quietly().run('npm test'),
+   *     pool.quietly().run('npm run build'),
+   *   ]);
+   */
+  pool(callback) { return new ProcessPool().start(callback); }
+}
+
+// ── Singleton ─────────────────────────────────────────────────────────────────
+
+const defaultProcess = new ProcessManager();
+
+module.exports                        = defaultProcess;
+module.exports.ProcessManager         = ProcessManager;
+module.exports.PendingProcess         = PendingProcess;
+module.exports.ProcessResult          = ProcessResult;
+module.exports.ProcessPool            = ProcessPool;
+module.exports.ProcessFailedException = ProcessFailedException;

package/src/providers/AdminServiceProvider.js

@@ -2,39 +2,96 @@
 
 const ServiceProvider = require('./ServiceProvider');
 const Admin           = require('../admin/Admin');
+const AdminAuth       = require('../admin/AdminAuth');
 
 /**
  * AdminServiceProvider
  *
- * Registers the Admin singleton and exposes it in the container.
+ * Boots the admin panel and wires it to the app's User model.
  *
- * Add to bootstrap/app.js:
- *   app.providers([..., AdminServiceProvider])
+ * ── Authentication flow ───────────────────────────────────────────────────
  *
- * Then register resources and mount:
- *   Admin.register(UserResource);
- *   Admin.mount(route, expressApp);
+ *  AdminAuth resolves the User model in this priority order:
+ *    1. Explicit model in config/admin.js  auth.model
+ *    2. The same model AuthServiceProvider resolved (app/models/User)
+ *    3. Built-in AuthUser (framework fallback)
+ *
+ *  It then enforces:
+ *    - user.is_active === true   (account not disabled)
+ *    - user.is_staff  === true   (has admin panel access)
+ *
+ *  Run `millas createsuperuser` to create your first admin user.
+ *  Run `millas migrate` first if you haven't — the users table must exist.
+ *
+ * ── Usage (bootstrap/app.js) ─────────────────────────────────────────────
+ *
+ *   module.exports = Millas.config()
+ *     .providers([AppServiceProvider])
+ *     .withAdmin()
+ *     .create();
+ *
+ * ── Optional config/admin.js ─────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     prefix: '/admin',
+ *     title:  'My App Admin',
+ *     auth: {
+ *       cookieMaxAge:   60 * 60 * 8,
+ *       rememberAge:    60 * 60 * 24 * 30,
+ *       maxAttempts:    5,
+ *       lockoutMinutes: 15,
+ *       // model: require('../app/models/AdminUser'),  // explicit override
+ *     },
+ *     // auth: false   — disable auth entirely (not recommended)
+ *   };
  */
 class AdminServiceProvider extends ServiceProvider {
   register(container) {
     container.instance('Admin',         Admin);
+    container.instance('AdminAuth',     AdminAuth);
     container.instance('AdminResource', require('../admin/resources/AdminResource').AdminResource);
     container.instance('AdminField',    require('../admin/resources/AdminResource').AdminField);
     container.instance('AdminFilter',   require('../admin/resources/AdminResource').AdminFilter);
   }
 
   async boot(container) {
+    const basePath = container.make('basePath') || process.cwd();
     let adminConfig = {};
     try {
-      adminConfig = require(process.cwd() + '/config/admin');
-    } catch { /* config is optional */ }
+      adminConfig = require(basePath + '/config/admin');
+    } catch { /* optional */ }
+
+    // auth: {} means "use the User model with is_staff gate" — the Django default.
+    // auth: false disables auth entirely.
+    // Anything else is passed through as-is (model override, cookie settings, etc.)
+    const authConfig = adminConfig.auth !== undefined ? adminConfig.auth : {};
 
     Admin.configure({
       prefix: adminConfig.prefix || '/admin',
       title:  adminConfig.title  || process.env.APP_NAME || 'Millas Admin',
       ...adminConfig,
+      auth: authConfig,
     });
+
+    // ── Wire basePath + User model into AdminAuth ──────────────────────────
+    // Pass basePath so AdminAuth._resolveUserModel() can find app/models/User
+    // without calling process.cwd() at request time.
+    AdminAuth.setBasePath(basePath);
+
+    // AuthServiceProvider runs before us (Database → Auth → Admin order).
+    // It already resolved app/models/User → AuthUser fallback and gave it
+    // to the Auth singleton. We grab the same model so AdminAuth and the
+    // API auth system always use the same table.
+    if (authConfig !== false) {
+      try {
+        const Auth = require('../auth/Auth');
+        // Auth._UserModel is the resolved model — reuse it directly
+        if (Auth._UserModel) {
+          AdminAuth.setUserModel(Auth._UserModel);
+        }
+      } catch { /* Auth not booted yet — AdminAuth will lazy-resolve */ }
+    }
   }
 }
 
-module.exports = AdminServiceProvider;
+module.exports = AdminServiceProvider;

package/src/providers/AuthServiceProvider.js

@@ -22,10 +22,11 @@ class AuthServiceProvider extends ServiceProvider {
   }
 
   async boot(container, app) {
+    const basePath = container.make('basePath') || process.cwd();
     // Load auth config
     let authConfig;
     try {
-      authConfig = require(process.cwd() + '/config/auth');
+      authConfig = require(basePath + '/config/auth');
     } catch {
       authConfig = {
         default: 'jwt',
@@ -33,12 +34,46 @@ class AuthServiceProvider extends ServiceProvider {
       };
     }
 
-    // Load the app's User model if it exists.
-    // Falls back to the built-in AuthUser so Auth always has a model to work with.
+    // ── Resolve the User model ──────────────────────────────────────────────
+    //
+    // Priority order (mirrors Django's AUTH_USER_MODEL pattern):
+    //
+    //   1. config/app.js → auth_user: 'User'
+    //      The model name is looked up in app/models/index.js exports.
+    //      This is the recommended approach — explicit and refactor-safe.
+    //
+    //   2. app/models/User.js (default export or named User export)
+    //      Conventional fallback — works if auth_user is not set and
+    //      the file exists at the default path.
+    //
+    //   3. Built-in AuthUser
+    //      Abstract base class — no table. Used only as a last resort
+    //      so Auth always has a model to work with during early dev.
+    //
     let UserModel;
     try {
-      UserModel = require(process.cwd() + '/app/models/User');
-    } catch {
+      // Step 1: read auth_user from config/app.js
+      let authUserName = null;
+      try {
+        const appConfig = require(basePath + '/config/app');
+        authUserName = appConfig.auth_user || null;
+      } catch { /* config/app.js missing or has no auth_user key */ }
+
+      if (authUserName) {
+        // Resolve by name from app/models/index.js
+        const modelsIndex = require(basePath + '/app/models/index');
+        const resolved    = modelsIndex[authUserName];
+        if (!resolved) {
+          throw new Error(
+            `[AuthServiceProvider] auth_user: '${authUserName}' not found in app/models/index.js.\n` +
+            `  Available exports: ${Object.keys(modelsIndex).join(', ')}`
+          );
+        }
+        UserModel = resolved;
+      }
+    } catch (err) {
+      if (err.message.includes('[AuthServiceProvider]')) throw err; // re-throw config errors
+      // Step 3: fall back to built-in AuthUser (abstract — no table)
       UserModel = require('../auth/AuthUser');
     }
 

package/src/providers/CacheStorageServiceProvider.js

@@ -18,7 +18,7 @@ class CacheServiceProvider extends ServiceProvider {
   async boot() {
     let cacheConfig;
     try {
-      cacheConfig = require(process.cwd() + '/config/cache');
+      cacheConfig = require((container.make('basePath') || process.cwd()) + '/config/cache');
     } catch {
       cacheConfig = {
         default: process.env.CACHE_DRIVER || 'memory',
@@ -48,7 +48,7 @@ class StorageServiceProvider extends ServiceProvider {
   async boot() {
     let storageConfig;
     try {
-      storageConfig = require(process.cwd() + '/config/storage');
+      storageConfig = require((container.make('basePath') || process.cwd()) + '/config/storage');
     } catch {
       storageConfig = {
         default: process.env.STORAGE_DRIVER || 'local',

package/src/providers/DatabaseServiceProvider.js

@@ -21,10 +21,11 @@ class DatabaseServiceProvider extends ServiceProvider {
   }
 
   async boot(container) {
+    const basePath = container.make('basePath') || process.cwd();
     // Load the database config
     let dbConfig;
     try {
-      dbConfig = require(process.cwd() + '/config/database');
+      dbConfig = require(basePath + '/config/database');
     } catch {
       // Fallback for tests / programmatic use
       dbConfig = {
@@ -42,4 +43,4 @@ class DatabaseServiceProvider extends ServiceProvider {
   }
 }
 
-module.exports = DatabaseServiceProvider;
+module.exports = DatabaseServiceProvider;

package/src/providers/LogServiceProvider.js

@@ -59,6 +59,9 @@ class LogServiceProvider extends ServiceProvider {
   beforeBoot(container) {
     let config = {};
     try {
+      // Note: beforeBoot runs before any container bindings exist.
+      // basePath is not yet available — process.cwd() is the correct fallback here.
+      // The path will be correct as long as `millas serve` is run from project root.
       config = require(process.cwd() + '/config/logging');
     } catch {
       // No config file — defaults already applied in logger/index.js
@@ -206,4 +209,4 @@ class LogServiceProvider extends ServiceProvider {
   }
 }
 
-module.exports = LogServiceProvider;
+module.exports = LogServiceProvider;

package/src/providers/MailServiceProvider.js

@@ -27,7 +27,7 @@ class MailServiceProvider extends ServiceProvider {
   async boot(container) {
     let mailConfig;
     try {
-      mailConfig = require(process.cwd() + '/config/mail');
+      mailConfig = require((container.make('basePath') || process.cwd()) + '/config/mail');
     } catch {
       mailConfig = {
         default:  process.env.MAIL_DRIVER || 'log',

package/src/providers/QueueServiceProvider.js

@@ -29,7 +29,7 @@ class QueueServiceProvider extends ServiceProvider {
   async boot(container) {
     let queueConfig;
     try {
-      queueConfig = require(process.cwd() + '/config/queue');
+      queueConfig = require((container.make('basePath') || process.cwd()) + '/config/queue');
     } catch {
       queueConfig = {
         default: process.env.QUEUE_DRIVER || 'sync',

package/src/router/MiddlewareRegistry.js

@@ -27,17 +27,42 @@ class MiddlewareRegistry {
 
   /**
    * Resolve a single alias to an Express-compatible function.
+   * Supports parameterised aliases: 'throttle:60,1' → 60 req per 1 minute.
+   *
    * @param {string|Function} aliasOrFn
    * @returns {Function}
    */
   resolve(aliasOrFn) {
     if (typeof aliasOrFn === 'function') return aliasOrFn;
 
-    const Handler = this._map[aliasOrFn];
+    // Parse parameterised alias: 'throttle:60,1' → alias='throttle', params=['60','1']
+    let alias  = aliasOrFn;
+    let params = [];
+    if (typeof aliasOrFn === 'string' && aliasOrFn.includes(':')) {
+      const colonIdx = aliasOrFn.indexOf(':');
+      alias  = aliasOrFn.slice(0, colonIdx);
+      params = aliasOrFn.slice(colonIdx + 1).split(',').map(s => s.trim());
+    }
+
+    const Handler = this._map[alias];
     if (!Handler) {
       throw new Error(`Middleware "${aliasOrFn}" is not registered.`);
     }
 
+    // If params provided, instantiate the class with them via fromParams() or constructor
+    if (params.length > 0) {
+      if (typeof Handler === 'function' && Handler.prototype &&
+          typeof Handler.prototype.handle === 'function') {
+        const instance = typeof Handler.fromParams === 'function'
+          ? Handler.fromParams(params)
+          : new Handler(...params);
+        return (req, res, next) => {
+          const result = instance.handle(req, res, next);
+          if (result && typeof result.catch === 'function') result.catch(next);
+        };
+      }
+    }
+
     // Pre-instantiated object with handle() method (e.g. new ThrottleMiddleware())
     if (typeof Handler === 'object' && Handler !== null && typeof Handler.handle === 'function') {
       return (req, res, next) => {
@@ -79,4 +104,4 @@ class MiddlewareRegistry {
   }
 }
 
-module.exports = MiddlewareRegistry;
+module.exports = MiddlewareRegistry;