millas 0.2.11 → 0.2.12-beta

package/src/commands/serve.js

@@ -3,48 +3,277 @@
 const chalk = require('chalk');
 const path = require('path');
 const fs = require('fs-extra');
+const fsnative = require('fs');
+const {fork} = require('child_process');
+const chokidar = require('chokidar');
+
+// ── ASCII banner ──────────────────────────────────────────────────────────────
+
+const BANNER_LINES = [
+    '  ███╗   ███╗██╗██╗     ██╗      █████╗ ███████╗',
+    '  ████╗ ████║██║██║     ██║     ██╔══██╗██╔════╝',
+    '  ██╔████╔██║██║██║     ██║     ███████║███████╗',
+    '  ██║╚██╔╝██║██║██║     ██║     ██╔══██║╚════██║',
+    '  ██║ ╚═╝ ██║██║███████╗███████╗██║  ██║███████║',
+    '  ╚═╝     ╚═╝╚═╝╚══════╝╚══════╝╚═╝  ╚═╝╚══════╝',
+];
+
+function printBanner(host, port) {
+    const env = process.env.NODE_ENV || 'development';
+    const ver = 'v' + (require('../../package.json').version || '0.1.2');
+    const url = `http://${host}:${port}`;
+    const hr = chalk.dim('  ' + '─'.repeat(54));
+
+    const envColour = env === 'production' ? chalk.red
+        : env === 'staging' ? chalk.yellow
+            : chalk.green;
+
+    process.stdout.write('\n');
+    for (const line of BANNER_LINES) {
+        process.stdout.write(chalk.bold.cyan(line) + '\n');
+    }
+    process.stdout.write('\n');
+    process.stdout.write(hr + '\n');
+    process.stdout.write(
+        '  ' +
+        chalk.dim(ver.padEnd(8)) +
+        chalk.dim('│') + '  ' +
+        envColour('⬤  ' + env) + '  ' +
+        chalk.dim('│') + '  ' +
+        chalk.bold.white(url) +
+        '\n'
+    );
+    process.stdout.write(hr + '\n\n');
+}
+
+// ── Hot reload watcher ────────────────────────────────────────────────────────
+
+/**
+ * Directories watched for changes (relative to project root).
+ * Watching parent dirs is enough — fs.watch recursive covers all descendants.
+ */
+const WATCH_DIRS = [
+    'app',
+    'routes',
+    'config',
+    'bootstrap',
+    'providers',
+    'middleware',
+];
+
+/** File extensions that trigger a reload when changed. */
+const WATCH_EXTS = new Set(['.js', '.mjs', '.cjs', '.json', '.njk', '.env']);
+
+/** How long to wait after the last change before restarting (ms). */
+const DEBOUNCE_MS = 300;
+
+class HotReloader {
+    constructor(bootstrapPath, env) {
+        this._bootstrap = bootstrapPath;
+        this._cwd = path.dirname(bootstrapPath.replace(/bootstrap.+$/, '')) ||
+            process.cwd();
+        this._env = env;
+        this._child = null;
+        this._watchers = [];
+        this._timer = null;
+        this._starting = false;
+        this._restarts = 0;
+    }
+
+    start() {
+        this._spawnChild();
+        this._watch();
+        this._handleSignals();
+    }
+
+    // ── Child process management ──────────────────────────────────────────────
+
+    _spawnChild() {
+        if (this._starting) return;
+        this._starting = true;
+
+        this._child = fork(this._bootstrap, [], {
+            env: {...process.env, ...this._env},
+            stdio: 'inherit',    // child shares parent's stdout/stderr — output appears inline
+            // detached: false   — child dies with parent
+        });
+
+        this._child.on('exit', (code, signal) => {
+            this._starting = false;
+            // Abnormal exit (crash) — don't auto-restart, let the developer fix it
+            if (code !== 0 && signal !== 'SIGTERM' && signal !== 'SIGKILL') {
+                process.stdout.write(
+                    '\n' + chalk.red('  ✖  App crashed') +
+                    chalk.dim(` (exit ${code ?? signal})`) +
+                    chalk.dim(' — waiting for changes…\n\n')
+                );
+            }
+        });
+
+        this._child.on('error', (err) => {
+            this._starting = false;
+            process.stderr.write(chalk.red(`\n  ✖  Child error: ${err.message}\n\n`));
+        });
+    }
+
+    _killChild(cb) {
+        if (!this._child || this._child.exitCode !== null) {
+            cb();
+            return;
+        }
+        this._child.once('exit', cb);
+        this._child.kill('SIGTERM');
+
+        // Force kill if graceful shutdown takes too long
+        setTimeout(() => {
+            if (this._child && this._child.exitCode === null) {
+                this._child.kill('SIGKILL');
+            }
+        }, 3000).unref();
+    }
+
+    _restart(changedFile) {
+        const rel = changedFile ? path.relative(process.cwd(), changedFile) : '';
+        const link = changedFile
+            ? `\x1b]8;;file://${changedFile}\x07${changedFile}\x1b]8;;\x07`
+            : '';
+
+        process.stdout.write(
+            '\n  ' + chalk.yellow('↺') + '  ' +
+            chalk.white('Reloading') +
+            (link ? '  ' + chalk.cyan(link) : '') +
+            '\n'
+        );
+
+        this._restarts++;
+
+        this._killChild(() => {
+            this._spawnChild();
+        });
+    }
+
+    // ── File watching ─────────────────────────────────────────────────────────
+
+    _watch() {
+        const cwd = process.cwd();
+        const watchPaths = [
+            ...WATCH_DIRS.map(d => path.join(cwd, d)),
+            path.join(cwd, '.env'),
+            path.join(cwd, '.env.local'),
+        ];
+
+        const watcher = chokidar.watch(watchPaths, {
+            persistent: true,
+            ignoreInitial: true,
+            ignored: /(^|[\/\\])\..(?!env)/,
+        });
+
+        watcher.on('all', (event, filePath) => {
+            if (WATCH_EXTS.has(path.extname(filePath))) {
+                this._scheduleRestart(filePath);
+            }
+        });
+
+        this._watchers.push(watcher);
+    }
+
+    _scheduleRestart(changedFile) {
+        clearTimeout(this._timer);
+        this._timer = setTimeout(() => {
+            this._restart(changedFile);
+        }, DEBOUNCE_MS);
+    }
+
+    _stopWatching() {
+        for (const w of this._watchers) {
+            try {
+                w.close();
+            } catch {
+            }
+        }
+        this._watchers = [];
+    }
+
+
+    // ── Signal handling ───────────────────────────────────────────────────────
+
+    _handleSignals() {
+        const cleanup = () => {
+            clearTimeout(this._timer);
+            this._stopWatching();
+            if (this._child) this._child.kill('SIGTERM');
+            process.exit(0);
+        };
+
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+    }
+}
+
+// ── Command definition ────────────────────────────────────────────────────────
 
 module.exports = function (program) {
-  program
-    .command('serve')
-    .description('Start the development server')
-    .option('-p, --port <port>', 'Port to listen on', '3000')
-    .option('-h, --host <host>', 'Host to bind to', 'localhost')
-    .action(async (options) => {
-      const appBootstrap = path.resolve(process.cwd(), 'bootstrap/app.js');
-
-      if (!fs.existsSync(appBootstrap)) {
-        console.error(chalk.red('\n  ✖ No Millas project found in current directory.\n'));
-        console.log(`  Make sure you are inside a Millas project and bootstrap/app.js exists.\n`);
-        process.exit(1);
-      }
 
-      console.log();
-      console.log(chalk.cyan('  ⚡ Millas Dev Server'));
-      console.log(chalk.gray(`  Starting on http://${options.host}:${options.port}\n`));
+    program
+        .command('serve')
+        .description('Start the development server with hot reload')
+        .option('-p, --port <port>', 'Port to listen on', '3000')
+        .option('-h, --host <host>', 'Host to bind to', 'localhost')
+        .option('--no-reload', 'Disable hot reload (run once, like production)')
+        .action((options) => {
+            const appBootstrap = path.resolve(process.cwd(), 'bootstrap/app.js');
 
-      process.env.MILLAS_PORT = options.port;
-      process.env.MILLAS_HOST = options.host;
-      process.env.NODE_ENV = process.env.NODE_ENV || 'development';
+            if (!fs.existsSync(appBootstrap)) {
+                process.stderr.write(chalk.red('\n  ✖  No Millas project found here.\n'));
+                process.stderr.write(chalk.dim('     Make sure bootstrap/app.js exists.\n\n'));
+                process.exit(1);
+            }
+
+            const env = {
+                MILLAS_PORT: options.port,
+                MILLAS_HOST: options.host,
+                NODE_ENV: process.env.NODE_ENV || 'development',
+                MILLAS_RELOAD: options.reload ? '1' : '0',
+            };
+
+            Object.assign(process.env, env);
+
+            printBanner(options.host, options.port);
+
+            const hotReload = options.reload !== false;
+
+            if (hotReload) {
+                // ── Hot reload mode ──────────────────────────────────────────────────
+                // Parent process watches files. App runs in a child process.
+                // On change: kill child, clear require cache, refork.
+                process.stdout.write(
+                    '  ' + chalk.green('✔') + '  ' +
+                    chalk.dim('Watching for file changes…') +
+                    '\n'
+                );
+
+                const reloader = new HotReloader(appBootstrap, env);
+                reloader.start();
+
+            } else {
+                // ── Single-run mode (--no-reload) ────────────────────────────────────
+                try {
+                    require(appBootstrap);
+                } catch (err) {
+                    process.stderr.write(chalk.red(`\n  ✖  Failed to start: ${err.message}\n\n`));
+                    if (process.env.DEBUG) process.stderr.write(chalk.dim(err.stack) + '\n');
+                    process.exit(1);
+                }
+            }
+        });
 
-      try {
-        require(appBootstrap);
-      } catch (err) {
-        console.error(chalk.red(`\n  ✖ Failed to start server: ${err.message}\n`));
-        console.error(err.stack);
-        process.exit(1);
-      }
-    });
 };
 
-// Exported so queue:work can import the pattern
-module.exports.requireProject = function(command) {
-  const path = require('path');
-  const fs   = require('fs-extra');
-  const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
-  if (!fs.existsSync(bootstrapPath)) {
-    const chalk = require('chalk');
-    console.error(chalk.red(`\n  ✖ Not inside a Millas project (${command}).\n`));
-    process.exit(1);
-  }
+// Exported so other commands (queue:work) can validate the project exists
+module.exports.requireProject = function (command) {
+    const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
+    if (!fsnative.existsSync(bootstrapPath)) {
+        process.stderr.write(chalk.red(`\n  ✖  Not inside a Millas project (${command}).\n\n`));
+        process.exit(1);
+    }
 };

package/src/container/Application.js

@@ -82,12 +82,23 @@ class Application {
   // ─── Lifecycle ───────────────────────────────────────────────────────────────
 
   /**
-   * Run the full provider register → boot lifecycle.
+   * Run the full provider lifecycle:
+   *   Phase 0 — beforeBoot (synchronous, global setup)
+   *   Phase 1 — register   (synchronous, container bindings)
+   *   Phase 2 — boot       (async, all bindings available)
+   *
+   * Emits: platform.booting → platform.booted
    */
   async boot() {
     if (this._booted) return this;
+
+    this._emitSync('platform.booting', { providers: this._providers.list() });
+
     await this._providers.boot();
     this._booted = true;
+
+    this._emitSync('platform.booted', { providers: this._providers.list() });
+
     return this;
   }
 
@@ -104,7 +115,7 @@ class Application {
    * Or use app.mount() which does all three in one call.
    */
   mountRoutes() {
-    this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
+    this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry, this._container);
     this._router.mountRoutes();
     return this;
   }
@@ -114,7 +125,7 @@ class Application {
    */
   mountFallbacks() {
     if (!this._router) {
-      this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
+      this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry, this._container);
     }
     this._router.mountFallbacks();
     return this;
@@ -126,30 +137,86 @@ class Application {
    * is mounted before this call.
    */
   mount() {
-    const router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
+    const router = new Router(this._express, this._route.getRegistry(), this._mwRegistry, this._container);
     router.mount();
     return this;
   }
 
   /**
    * Start the HTTP server.
+   * Emits: platform.listening
    */
   listen(port, host, callback) {
-    const _port = port || parseInt(process.env.APP_PORT, 10) || 3000;
+    const _port = port || parseInt(process.env.APP_PORT,   10) || 3000;
     const _host = host || process.env.MILLAS_HOST || 'localhost';
 
-    this._express.listen(_port, _host, () => {
+    const server = this._express.listen(_port, _host, () => {
       if (!process.env.MILLAS_ROUTE_LIST) {
+        const chalk      = _tryChalk();
         const routeCount = this._route.list().length;
-        console.log(`\n  ⚡ Millas running at http://${_host}:${_port}`);
-        console.log(`  ${routeCount} route(s) registered\n`);
+
+        // Use process.stdout.write directly so these lines always appear
+        // regardless of log level — even if console is patched and debug is off.
+        process.stdout.write(
+          '  ' + chalk.dim('›') + '  ' +
+          chalk.white(routeCount + ' route' + (routeCount !== 1 ? 's' : '') + ' registered') +
+          '\n'
+        );
+        process.stdout.write(
+          '  ' + chalk.dim('›') + '  ' +
+          chalk.dim('Press ') + chalk.bold('Ctrl+C') + chalk.dim(' to stop') +
+          '\n\n'
+        );
       }
+
+      this._emitSync('platform.listening', { port: _port, host: _host });
+
       if (typeof callback === 'function') callback(_port, _host);
     });
 
+    this._server = server;
+    return this;
+  }
+
+  /**
+   * Graceful shutdown — emits platform.shutting_down, then closes the server.
+   * Call this instead of process.exit() for clean teardown.
+   *
+   *   process.on('SIGTERM', () => app.shutdown());
+   */
+  async shutdown(code = 0) {
+    this._emitSync('platform.shutting_down', {});
+    if (this._server) {
+      await new Promise(resolve => this._server.close(resolve));
+    }
+    process.exit(code);
+  }
+
+  // ─── Platform event bus ───────────────────────────────────────────────────
+
+  /**
+   * Listen to a platform lifecycle event.
+   *
+   *   app.on('platform.booted', ({ providers }) => { ... });
+   *   app.on('platform.listening', ({ port, host }) => { ... });
+   *   app.on('platform.shutting_down', () => process.cleanup());
+   */
+  on(event, fn) {
+    if (!this._platformListeners) this._platformListeners = new Map();
+    if (!this._platformListeners.has(event)) this._platformListeners.set(event, []);
+    this._platformListeners.get(event).push(fn);
     return this;
   }
 
+  /** Synchronous platform event dispatch (fire-and-forget, no await). */
+  _emitSync(event, data) {
+    if (!this._platformListeners) return;
+    const listeners = this._platformListeners.get(event) || [];
+    for (const fn of listeners) {
+      try { fn(data); } catch {}
+    }
+  }
+
   // ─── Container Proxy ─────────────────────────────────────────────────────────
 
   /**
@@ -206,3 +273,16 @@ class Application {
 }
 
 module.exports = Application;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// Safely require chalk — it ships with Millas but we guard in case of oddities
+function _tryChalk() {
+  try { return require('chalk'); } catch {
+    // Fallback: no-op chalk that returns strings unchanged
+    const id = s => s;
+    const p  = new Proxy({}, { get: () => p, apply: (_, __, [s]) => String(s || '') });
+    p.dim = id; p.bold = p; p.white = id;
+    return p;
+  }
+}