millas 0.2.13 → 0.2.15

package/src/commands/serve.js

@@ -198,13 +198,15 @@ module.exports = function (program) {
     program
         .command('serve')
         .description('Start the development server with hot reload')
-        .option('-p, --port <port>', 'Port to listen on', '3000')
+        .option('-p, --port <port>', 'Port to listen on')
         .option('-h, --host <host>', 'Host to bind to', 'localhost')
         .option('--no-reload', 'Disable hot reload (run once, like production)')
         .action((options) => {
 
+            require('dotenv').config({ path: path.resolve(process.cwd(), '.env') });
+
             const restoreAfterPatch = patchConsole(Logger,"SystemOut")
-            const appBootstrap = path.resolve(process.cwd(), 'bootstrap/app.js');
+            let appBootstrap = path.resolve(process.cwd(), 'bootstrap/app.js');
 
             if (!fs.existsSync(appBootstrap)) {
                 process.stderr.write(chalk.red('\n  ✖  No Millas project found here.\n'));
@@ -212,8 +214,7 @@ module.exports = function (program) {
                 process.exit(1);
             }
 
-
-            const publicPort = parseInt(options.port, 10) || 3000;
+            const publicPort = parseInt(options.port ||process.env.APP_PORT, 10) || 3000;
             const publicHost = options.host || 'localhost';
 
             const env = {
@@ -227,7 +228,6 @@ module.exports = function (program) {
             printBanner(publicHost, publicPort);
 
             if (options.reload !== false) {
-
                 new HotReloader(appBootstrap, publicPort, publicHost).start();
             } else {
                 try {

package/src/console/Command.js

@@ -0,0 +1,337 @@
+'use strict';
+
+const chalk = require('chalk');
+
+/**
+ * Command
+ *
+ * Base class for all custom Millas console commands.
+ * Mirrors Laravel's Artisan command / Django's BaseCommand.
+ *
+ * ── Defining a command ────────────────────────────────────────────────────────
+ *
+ *   // app/commands/SendDigestCommand.js
+ *   const { Command } = require('millas/console');
+ *
+ *   class SendDigestCommand extends Command {
+ *     static signature    = 'email:digest';
+ *     static description  = 'Send the weekly digest email to all subscribers';
+ *
+ *     // Optional: define arguments and options
+ *     static args = [
+ *       { name: 'type', description: 'Digest type (weekly|daily)', default: 'weekly' },
+ *     ];
+ *
+ *     static options = [
+ *       { flag: '--dry-run', description: 'Preview without sending' },
+ *       { flag: '--limit <n>', description: 'Max recipients', default: '100' },
+ *     ];
+ *
+ *     async handle() {
+ *       const type  = this.argument('type');
+ *       const limit = this.option('limit');
+ *       const dry   = this.option('dryRun');
+ *
+ *       this.info(`Sending ${type} digest to up to ${limit} users…`);
+ *
+ *       if (dry) {
+ *         this.warn('Dry run — no emails sent.');
+ *         return;
+ *       }
+ *
+ *       // … your logic …
+ *       this.success('Done!');
+ *     }
+ *   }
+ *
+ *   module.exports = SendDigestCommand;
+ *
+ * ── Running ───────────────────────────────────────────────────────────────────
+ *
+ *   millas call email:digest
+ *   millas call email:digest weekly --limit 50 --dry-run
+ *
+ * ── Output helpers ────────────────────────────────────────────────────────────
+ *
+ *   this.line(msg)      — plain output
+ *   this.info(msg)      — cyan
+ *   this.success(msg)   — green  ✔
+ *   this.warn(msg)      — yellow ⚠
+ *   this.error(msg)     — red    ✖
+ *   this.comment(msg)   — dim / gray
+ *   this.newLine()      — blank line
+ *   this.table(headers, rows)   — formatted table
+ *
+ * ── Input helpers ─────────────────────────────────────────────────────────────
+ *
+ *   this.argument(name)   — positional arg value
+ *   this.option(name)     — option value (camelCase: --dry-run → dryRun)
+ *   this.ask(question)    — interactive prompt, returns Promise<string>
+ *   this.secret(question) — hidden input (passwords), returns Promise<string>
+ *   this.confirm(question, default?) — yes/no prompt, returns Promise<boolean>
+ *
+ * ── Exit ──────────────────────────────────────────────────────────────────────
+ *
+ *   return;              — success (exit 0)
+ *   this.fail(msg)       — print error + exit 1
+ */
+class Command {
+  /**
+   * The CLI signature — used as the command name.
+   * Use colons for namespacing: 'email:digest', 'cache:clear', 'db:seed'
+   *
+   * @type {string}
+   */
+  static signature = '';
+
+  /**
+   * Short description shown in `millas --help` and `millas list`.
+   *
+   * @type {string}
+   */
+  static description = '';
+
+  /**
+   * Positional arguments.
+   * Each entry: { name: string, description?: string, default?: * }
+   *
+   * @type {Array<{ name: string, description?: string, default?: * }>}
+   */
+  static args = [];
+
+  /**
+   * Named options / flags.
+   * Each entry: { flag: string, description?: string, default?: * }
+   * flag examples: '--dry-run', '--limit <n>', '-f, --force'
+   *
+   * @type {Array<{ flag: string, description?: string, default?: * }>}
+   */
+  static options = [];
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  constructor() {
+    this._args    = {};
+    this._opts    = {};
+  }
+
+  /**
+   * Populate the command with parsed CLI values.
+   * Called by CommandLoader before handle().
+   *
+   * @param {object} args    — { argName: value, … }
+   * @param {object} options — { optName: value, … }
+   * @internal
+   */
+  _hydrate(args, options) {
+    this._args = args    || {};
+    this._opts = options || {};
+  }
+
+  // ── Input ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Get a positional argument value by name.
+   *
+   *   const name = this.argument('name');
+   *
+   * @param {string} name
+   * @returns {*}
+   */
+  argument(name) {
+    return this._args[name];
+  }
+
+  /**
+   * Get an option value by name (camelCase).
+   * Flags like --dry-run become dryRun.
+   *
+   *   const limit = this.option('limit');
+   *   const dry   = this.option('dryRun');
+   *
+   * @param {string} name
+   * @returns {*}
+   */
+  option(name) {
+    return this._opts[name];
+  }
+
+  /**
+   * Prompt the user for input.
+   *
+   *   const name = await this.ask('What is your name?');
+   *
+   * @param {string} question
+   * @returns {Promise<string>}
+   */
+  ask(question) {
+    return _prompt(question + ' ');
+  }
+
+  /**
+   * Prompt the user for a secret (input hidden — for passwords).
+   *
+   *   const pass = await this.secret('Password:');
+   *
+   * @param {string} question
+   * @returns {Promise<string>}
+   */
+  secret(question) {
+    return _promptSecret(question + ' ');
+  }
+
+  /**
+   * Prompt for a yes/no confirmation.
+   *
+   *   const ok = await this.confirm('Are you sure?');
+   *   const ok = await this.confirm('Delete all records?', false);
+   *
+   * @param {string}  question
+   * @param {boolean} [defaultValue=true]
+   * @returns {Promise<boolean>}
+   */
+  async confirm(question, defaultValue = true) {
+    const hint   = defaultValue ? '(Y/n)' : '(y/N)';
+    const answer = await _prompt(`${question} ${hint} `);
+    const trimmed = (answer || '').trim().toLowerCase();
+    if (!trimmed) return defaultValue;
+    return trimmed === 'y' || trimmed === 'yes';
+  }
+
+  // ── Output ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Write a plain line to stdout.
+   * @param {string} [msg='']
+   */
+  line(msg = '') {
+    process.stdout.write(msg + '\n');
+  }
+
+  /**
+   * Write a blank line.
+   */
+  newLine() {
+    process.stdout.write('\n');
+  }
+
+  /**
+   * Informational message (cyan).
+   * @param {string} msg
+   */
+  info(msg) {
+    this.line(chalk.cyan(`  ${msg}`));
+  }
+
+  /**
+   * Success message (green ✔).
+   * @param {string} msg
+   */
+  success(msg) {
+    this.line(chalk.green(`  ✔  ${msg}`));
+  }
+
+  /**
+   * Warning message (yellow ⚠).
+   * @param {string} msg
+   */
+  warn(msg) {
+    this.line(chalk.yellow(`  ⚠  ${msg}`));
+  }
+
+  /**
+   * Error message (red ✖). Does NOT exit — use fail() to exit.
+   * @param {string} msg
+   */
+  error(msg) {
+    this.line(chalk.red(`  ✖  ${msg}`));
+  }
+
+  /**
+   * Dimmed / comment message.
+   * @param {string} msg
+   */
+  comment(msg) {
+    this.line(chalk.dim(`  // ${msg}`));
+  }
+
+  /**
+   * Print an error and exit with code 1.
+   * @param {string} msg
+   */
+  fail(msg) {
+    this.error(msg);
+    process.exit(1);
+  }
+
+  /**
+   * Render a simple table.
+   *
+   *   this.table(
+   *     ['ID', 'Name',  'Email'],
+   *     [[1,   'Alice', 'alice@example.com'],
+   *      [2,   'Bob',   'bob@example.com']],
+   *   );
+   *
+   * @param {string[]}   headers
+   * @param {Array[]}    rows
+   */
+  table(headers, rows) {
+    if (!headers.length) return;
+
+    // Compute column widths
+    const widths = headers.map((h, i) => {
+      const colValues = [String(h), ...rows.map(r => String(r[i] ?? ''))];
+      return Math.max(...colValues.map(v => v.length));
+    });
+
+    const hr  = '  ' + widths.map(w => '─'.repeat(w + 2)).join('┼') ;
+    const fmt = (cells, color) => '  ' + cells
+      .map((c, i) => color(String(c ?? '').padEnd(widths[i])))
+      .join(chalk.dim(' │ '));
+
+    this.newLine();
+    this.line(fmt(headers, chalk.bold));
+    this.line(chalk.dim(hr));
+    for (const row of rows) {
+      this.line(fmt(row, v => v));
+    }
+    this.newLine();
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+  /**
+   * The command's entry point. Override this in your command.
+   *
+   * @returns {Promise<void>}
+   */
+  async handle() {
+    throw new Error(`[Command] "${this.constructor.signature}" must implement handle().`);
+  }
+}
+
+// ── Prompt helpers ────────────────────────────────────────────────────────────
+
+function _prompt(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => { rl.close(); resolve(answer); });
+  });
+}
+
+function _promptSecret(question) {
+  if (!process.stdin.isTTY) return _prompt(question);
+  return new Promise(resolve => {
+    process.stdout.write(question);
+    const rl = require('readline').createInterface({
+      input:    process.stdin,
+      output:   new (require('stream').Writable)({ write(c, e, cb) { cb(); } }),
+      terminal: true,
+    });
+    rl.question('', answer => { rl.close(); process.stdout.write('\n'); resolve(answer); });
+  });
+}
+
+module.exports = Command;

package/src/console/CommandLoader.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * CommandLoader
+ *
+ * Discovers all custom commands in app/commands/ and registers
+ * them as Commander sub-commands under `millas call <signature>`.
+ *
+ * Each file must export a class that extends Command:
+ *
+ *   module.exports = SendDigestCommand;
+ *
+ * CommandLoader reads the static `signature`, `description`, `args`,
+ * and `options` properties to wire up Commander automatically —
+ * no manual registration needed.
+ */
+class CommandLoader {
+  /**
+   * @param {string} commandsDir — absolute path to app/commands/
+   */
+  constructor(commandsDir) {
+    this._dir      = commandsDir;
+    this._commands = new Map(); // signature → CommandClass
+  }
+
+  /**
+   * Scan commandsDir and load all valid Command subclasses.
+   * Files that throw on require() are reported as warnings — never silently skipped.
+   * Files that don't export a valid Command subclass are skipped with a clear message.
+   *
+   * @returns {Map<string, typeof Command>}
+   */
+  load() {
+    if (!fs.existsSync(this._dir)) return this._commands;
+
+    const chalk = require('chalk');
+
+    const files = fs.readdirSync(this._dir)
+      .filter(f => f.endsWith('.js') && !f.startsWith('.') && !f.startsWith('_'));
+
+    for (const file of files) {
+      const filePath = path.join(this._dir, file);
+
+      let CommandClass;
+      try {
+        CommandClass = require(filePath);
+      } catch (err) {
+        process.stderr.write(
+          chalk.red(`\n  ✖  Failed to load command file: ${chalk.bold(file)}\n`) +
+          chalk.dim(`     ${err.message}\n`) +
+          (process.env.DEBUG ? chalk.dim(err.stack + '\n') : '') +
+          '\n'
+        );
+        continue;
+      }
+
+      if (!CommandClass || typeof CommandClass !== 'function') {
+        process.stderr.write(
+          chalk.yellow(`  ⚠  Skipping ${chalk.bold(file)} — does not export a class.\n`)
+        );
+        continue;
+      }
+
+      if (!CommandClass.signature) {
+        process.stderr.write(
+          chalk.yellow(`  ⚠  Skipping ${chalk.bold(file)} — missing static signature.\n`)
+        );
+        continue;
+      }
+
+      if (typeof CommandClass.prototype.handle !== 'function') {
+        process.stderr.write(
+          chalk.yellow(`  ⚠  Skipping ${chalk.bold(file)} — missing handle() method.\n`)
+        );
+        continue;
+      }
+
+      this._commands.set(CommandClass.signature, CommandClass);
+    }
+
+    return this._commands;
+  }
+
+  /**
+   * Register all loaded commands onto a Commander `program` instance.
+   * Called by the `millas call` command to dynamically attach sub-commands.
+   *
+   * @param {import('commander').Command} program
+   */
+  register(program) {
+    this.load();
+
+    for (const [, CommandClass] of this._commands) {
+      this._registerOne(program, CommandClass);
+    }
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  _registerOne(program, CommandClass) {
+    const sig  = CommandClass.signature;
+    const desc = CommandClass.description || '';
+    const args = CommandClass.args    || [];
+    const opts = CommandClass.options || [];
+
+    // Build Commander argument string: <required> or [optional]
+    const argStr = args
+      .map(a => a.default !== undefined ? `[${a.name}]` : `<${a.name}>`)
+      .join(' ');
+
+    const fullSig = argStr ? `${sig} ${argStr}` : sig;
+
+    let cmd = program.command(fullSig).description(desc);
+
+    // Register each option
+    for (const opt of opts) {
+      if (opt.default !== undefined) {
+        cmd = cmd.option(opt.flag, opt.description || '', opt.default);
+      } else {
+        cmd = cmd.option(opt.flag, opt.description || '');
+      }
+    }
+
+    // Action handler
+    cmd.action(async (...cliArgs) => {
+      // Commander passes positional args first, then the options object last
+      const options  = cliArgs[cliArgs.length - 1];
+      const posArgs  = cliArgs.slice(0, cliArgs.length - 1);
+
+      // Build named arg map
+      const argMap = {};
+      for (let i = 0; i < args.length; i++) {
+        argMap[args[i].name] = posArgs[i] !== undefined
+          ? posArgs[i]
+          : args[i].default;
+      }
+
+      const instance = new CommandClass();
+      instance._hydrate(argMap, options);
+
+      try {
+        await instance.handle();
+      } catch (err) {
+        const chalk = require('chalk');
+        process.stderr.write(chalk.red(`\n  ✖  ${sig} failed: ${err.message}\n`));
+        if (process.env.DEBUG) process.stderr.write(err.stack + '\n');
+        process.exit(1);
+      }
+    });
+  }
+
+  /**
+   * Return all loaded command signatures.
+   * @returns {string[]}
+   */
+  signatures() {
+    this.load();
+    return [...this._commands.keys()];
+  }
+}
+
+module.exports = CommandLoader;

package/src/console/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const Command       = require('./Command');
+const CommandLoader = require('./CommandLoader');
+
+module.exports = { Command, CommandLoader };

package/src/container/AppInitializer.js

@@ -55,7 +55,10 @@ class AppInitializer {
      */
     async boot() {
         await this.bootKernel();
-        await this._serve();
+        if (!process.env.MILLAS_CLI_MODE) {
+            await this._serve();
+        }
+        return this._kernel;
     }
 
     /**
@@ -82,6 +85,18 @@ class AppInitializer {
         const basePath          = cfg.basePath || process.cwd();
         const appConfig         = SecurityBootstrap.loadConfig(basePath + '/config/app');
         SecurityBootstrap.apply(this._adapter.nativeApp || expressApp, appConfig);
+
+        // ── CORS — applied immediately after security, before routes ──────────
+        // Only active when .withCors() was called in bootstrap/app.js.
+        // Config is read from the cors: {} block in config/app.js (already loaded
+        // above as appConfig). No cors key = CorsMiddleware class defaults apply.
+        if (cfg.cors !== null && cfg.cors !== undefined) {
+            const CorsMiddleware = require('../middleware/CorsMiddleware');
+            const corsMiddleware = new CorsMiddleware(appConfig.cors || {});
+            (this._adapter.nativeApp || expressApp).use(
+                this._adapter.wrapMiddleware(corsMiddleware, null)
+            );
+        }
         // ─────────────────────────────────────────────────────────────────────
 
         for (const mw of (cfg.adapterMiddleware || [])) {
@@ -130,6 +145,23 @@ class AppInitializer {
                 }
             }
 
+            // ── Docs panel ────────────────────────────────────────────────
+            if (cfg.docs !== null && cfg.docs !== undefined) {
+                try {
+                    const Docs = require('../docs/Docs');
+                    // Wire live RouteRegistry now that routes are fully mounted
+                    try {
+                        Docs.setRouteRegistry(this._kernel.route.getRegistry());
+                    } catch {}
+                    if (cfg.docs && Object.keys(cfg.docs).length) {
+                        Docs.configure(cfg.docs);
+                    }
+                    Docs.mount(this._adapter.nativeApp);
+                } catch (err) {
+                    process.stderr.write(`[millas] Docs mount failed: ${err.message}\n`);
+                }
+            }
+
             this._kernel.mountFallbacks();
 
             const server = new HttpServer(this._kernel, {
@@ -178,6 +210,12 @@ class AppInitializer {
             if (p) providers.push(p);
         }
 
+        // ── 4b. Docs — on when .withDocs() was called ────────────────────────
+        if (cfg.docs !== null && cfg.docs !== undefined) {
+            const p = load('../docs/DocsServiceProvider');
+            if (p) providers.push(p);
+        }
+
         // ── 5. Cache + Storage ───────────────────────────────────────────────
         if (cfg.cache !== false || cfg.storage !== false) {
             const p = load('../providers/CacheStorageServiceProvider');
@@ -208,6 +246,15 @@ class AppInitializer {
         // ── 9. i18n — opt-in via config/app.js use_i18n: true ───────────────
         // Mirrors Django's USE_I18N = True in settings.py.
         // Booted last so translations are available in all request handlers.
+        // ── 9. Encryption — always on (APP_KEY drives it) ────────────────────
+        // Mirrors Laravel: the encrypter is always bound so Crypt / Encrypt
+        // facades work out of the box. If APP_KEY is absent a clear error is
+        // thrown on first use, not at boot — apps without encryption still start.
+        {
+            const p = load('../providers/EncryptionServiceProvider');
+            if (p) providers.push(p);
+        }
+
         if (this._resolveI18nEnabled(cfg)) {
             const p = load('../i18n/I18nServiceProvider');
             if (p) providers.push(p);

package/src/container/Application.js

@@ -304,7 +304,9 @@ class Application {
         this._container.instance('url', urlGenerator);
 
         const { HashManager } = require('../hashing/Hash');
-        const hashManager = new HashManager({ default: 'bcrypt', bcrypt: { rounds: 12 } });
+        let _hashRounds = 12;
+        try { const _appCfg = require(basePath + '/config/app'); if (_appCfg.hashing?.rounds) _hashRounds = _appCfg.hashing.rounds; } catch {}
+        const hashManager = new HashManager({ default: 'bcrypt', bcrypt: { rounds: _hashRounds } });
         this._container.instance('hash', hashManager);
 
         const ProcessManager = require('../process/Process').ProcessManager;

package/src/container/HttpServer.js

@@ -92,7 +92,6 @@ class HttpServer {
             this._options.port ||
             parseInt(process.env.MILLAS_INTERNAL_PORT, 10) ||
             parseInt(process.env.APP_PORT, 10) ||
-            parseInt(process.env.PORT, 10) ||
             3000;
 
         return this._normalizePort(raw);