millas 0.2.12-beta → 0.2.12-beta-2

package/src/container/HttpServer.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * HttpServer
+ *
+ * Owns everything that belongs to the process/server layer — the things
+ * Express puts in bin/www that have nothing to do with your app logic:
+ *
+ *   - Port normalisation and validation
+ *   - EADDRINUSE / EACCES error handling with clear messages
+ *   - Startup log (route count, URL, Ctrl+C hint)
+ *   - IPC ready signal to the hot-reload proxy (millas serve)
+ *   - Graceful shutdown on SIGTERM / SIGINT
+ *
+ * The Application kernel knows nothing about any of this.
+ *
+ * ── Usage in bootstrap/server.js ────────────────────────────────────────────
+ *
+ *   const app    = require('./app');          // configured Millas app, no listen()
+ *   const server = new HttpServer(app);
+ *   server.start();
+ *
+ * ── Advanced ─────────────────────────────────────────────────────────────────
+ *
+ *   new HttpServer(app, {
+ *     port:     4000,
+ *     host:     '0.0.0.0',
+ *     onStart:  (port, host) => console.log(`up on ${host}:${port}`),
+ *     onShutdown: () => db.close(),
+ *   }).start();
+ */
+class HttpServer {
+    /**
+     * @param {import('./Application')} app     — booted Millas Application instance
+     * @param {object}                  options
+     * @param {number}  [options.port]
+     * @param {string}  [options.host]
+     * @param {Function}[options.onStart]     — (port, host) => void, called after listen
+     * @param {Function}[options.onShutdown]  — async () => void, called before process.exit
+     */
+    constructor(app, options = {}) {
+        this._app = app;
+        this._options = options;
+    }
+
+    /**
+     * Resolve port, boot the server, wire signals.
+     * Returns a Promise that resolves once the server is listening.
+     */
+    async start() {
+        const port = this._resolvePort();
+        const host = this._options.host
+            || process.env.MILLAS_HOST
+            || process.env.HOST
+            || 'localhost';
+
+        // Boot providers if not already done
+        if (!this._app._booted) {
+            await this._app.boot();
+        }
+
+        // Mount routes + fallbacks if not already mounted
+        if (!this._app._router) {
+            this._app.mount();
+        }
+
+        // Start listening — may throw on EADDRINUSE / EACCES
+        try {
+            await this._app.listen(port, host);
+        } catch (err) {
+            this._handleListenError(err, port);
+            return; // _handleListenError always exits
+        }
+
+        // Notify the millas serve hot-reload proxy that we're ready
+        if (typeof process.send === 'function') {
+            process.send({type: 'ready', port});
+        }
+
+        // User callback
+        if (typeof this._options.onStart === 'function') {
+            this._options.onStart(port, host);
+        }
+        this._handleSignals();
+
+    }
+
+    // ── Private ────────────────────────────────────────────────────────────────
+
+    _resolvePort() {
+        const raw =
+            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);
+    }
+
+    _normalizePort(val) {
+        const n = parseInt(val, 10);
+        if (isNaN(n)) return val;   // named pipe — pass through
+        if (n >= 0) return n;
+        return 3000;
+    }
+
+    _handleListenError(err, port) {
+        const bind = typeof port === 'string' ? `pipe ${port}` : `port ${port}`;
+
+        switch (err.code) {
+            case 'EACCES':
+                console.error(
+                    `✖  ${bind} requires elevated privileges.\n` +
+                    `     Try a port above 1024 or run with sudo.`
+                );
+                break;
+
+            case 'EADDRINUSE':
+                console.error(
+                    `✖  ${bind} is already in use.\n` +
+                    `     Another process is listening on that port.\n` +
+                    `     Try: APP_PORT=3001 millas serve`
+                );
+                break;
+
+            default:
+                console.error(`✖  Listen error: ${err.message}`);
+                if (process.env.APP_DEBUG) console.error(err.stack + '\n');
+        }
+
+        process.exit(1);
+    }
+
+
+    _handleSignals() {
+        const shutdown = async (signal) => {
+            process.exit(0);
+            // process.stdout.write(`\n  Shutting down (${signal})…\n`);
+            //
+            // if (typeof this._options.onShutdown === 'function') {
+            //     try {
+            //         await this._options.onShutdown();
+            //     } catch {
+            //     }
+            // }
+            //
+            // await this._app.shutdown(0);
+        };
+
+        process.once('SIGTERM', () => shutdown("SIGTERM"));
+        process.once('SIGINT', () => shutdown('SIGINT'));
+    }
+}
+
+module.exports = HttpServer;

package/src/container/MillasApp.js

@@ -1,299 +1,49 @@
 'use strict';
 
-const express  = require('express');
-const Application = require('./Application');
+const MillasConfig = require('./MillasConfig');
 
 /**
- * MillasApp
- *
- * A clean factory wrapper around Application that wires up Express,
- * core providers, routes, and the admin panel automatically.
- *
- * Reduces bootstrap/app.js from ~60 lines to ~8.
- *
- * ── Usage ───────────────────────────────────────────────────────────────────
+ * Millas
+
+ * ── bootstrap/app.js ────────────────────────────────────────────────────────
  *
- *   require('dotenv').config();
- *   const { MillasApp } = require('millas');
- *   const AppServiceProvider = require('../providers/AppServiceProvider');
+ *   const { Millas } = require('millas');
  *
- *   const app = MillasApp.create()
+ *   module.exports = Millas.config()
  *     .providers([AppServiceProvider])
  *     .routes(Route => {
  *       require('../routes/web')(Route);
  *       require('../routes/api')(Route);
  *     })
- *     .withAdmin();
- *
- *   module.exports = app.start();
- *
- * ── Escape hatches ──────────────────────────────────────────────────────────
- *
- *   // Access the raw Express app
- *   app.express.use(someExpressMiddleware());
- *
- *   // Access the DI container
- *   app.container.make('db');
- *
- *   // Access the underlying Application kernel
- *   app.kernel
+ *     .withAdmin()
+ *     .create();
  *
- * ── Advanced ────────────────────────────────────────────────────────────────
+ * That is everything a developer writes. The rest is handled internally.
  *
- *   MillasApp.create({
- *     // Disable a core provider
- *     mail:    false,
- *     queue:   false,
+ * Millas.config()   → MillasConfig  (chainable, collects config only)
+ * .create()         → MillasInstance (sealed carrier, no callable methods)
  *
- *     // Custom admin prefix
- *     admin:   { prefix: '/cms', title: 'My CMS' },
- *
- *     // Add Express middleware before routes
- *     expressMiddleware: [cors(), helmet()],
- *
- *     // Called once the app is listening
- *     onStart: (port, host) => console.log(`Running on ${host}:${port}`),
- *   })
+ * The framework's AppInitialiser receives the MillasInstance, reads its
+ * config, and boots the full application — adapter, kernel, providers,
+ * routes, admin, HTTP server — without the developer being involved.
  */
-class MillasApp {
-
-  // ─── Factory ──────────────────────────────────────────────────────────────
-
-  /**
-   * Create a new MillasApp instance.
-   * @param {object} [options]
-   * @param {boolean} [options.database=true]   — register DatabaseServiceProvider
-   * @param {boolean} [options.cache=true]      — register CacheServiceProvider
-   * @param {boolean} [options.storage=true]    — register StorageServiceProvider
-   * @param {boolean} [options.mail=true]       — register MailServiceProvider
-   * @param {boolean} [options.queue=true]      — register QueueServiceProvider
-   * @param {boolean} [options.events=true]     — register EventServiceProvider
-   * @param {boolean} [options.logging=true]    — register LogServiceProvider
-   * @param {Array}   [options.expressMiddleware] — Express middleware applied before routes
-   * @param {Function}[options.onStart]         — callback(port, host) after listen
-   */
-  static create(options = {}) {
-    return new MillasApp(options);
-  }
-
-  constructor(options = {}) {
-    this._options      = options;
-    this._userProviders = [];
-    this._routesCb     = null;
-    this._adminOptions = null;   // null = no admin; object/true = mount admin
-    this._expressApp   = null;
-    this._kernel       = null;
-    this._started      = false;
-  }
-
-  // ─── Fluent API ───────────────────────────────────────────────────────────
-
-  /**
-   * Register application service providers.
-   *
-   *   .providers([AppServiceProvider, PaymentServiceProvider])
-   */
-  providers(list = []) {
-    this._userProviders.push(...list);
-    return this;
-  }
-
-  /**
-   * Define application routes.
-   *
-   *   .routes(Route => {
-   *     require('../routes/web')(Route);
-   *     require('../routes/api')(Route);
-   *   })
-   */
-  routes(callback) {
-    this._routesCb = callback;
-    return this;
-  }
-
-  /**
-   * Register a named middleware alias.
-   * Must be called before start().
-   *
-   *   .middleware('verified', EmailVerifiedMiddleware)
-   */
-  middleware(alias, handler) {
-    if (!this._pendingMiddleware) this._pendingMiddleware = [];
-    this._pendingMiddleware.push({ alias, handler });
-    return this;
-  }
-
-  /**
-   * Mount the admin panel.
-   *
-   *   .withAdmin()                          // default /admin
-   *   .withAdmin({ prefix: '/cms' })        // custom prefix
-   *   .withAdmin({ prefix: '/admin', auth: { users: [...] } })
-   */
-  withAdmin(options = {}) {
-    this._adminOptions = options;
-    return this;
-  }
-
-  // ─── Start ────────────────────────────────────────────────────────────────
-
+const Millas = {
   /**
-   * Boot all providers, mount routes, and start listening.
-   * Returns an object with { app, expressApp, route } for module.exports.
+   * Start building an application config.
+   * Equivalent to Millas.config().configure(basePath).
    *
-   * Safe to await if you need to run code after boot:
-   *   const { app } = await MillasApp.create()...start();
-   */
-  start() {
-    // Build Express + Application kernel
-    this._expressApp = express();
-    this._expressApp.use(express.json());
-    this._expressApp.use(express.urlencoded({ extended: true }));
-
-    // Apply any extra Express middleware (e.g. helmet, cors)
-    for (const mw of (this._options.expressMiddleware || [])) {
-      this._expressApp.use(mw);
-    }
-
-    this._kernel = new Application(this._expressApp);
-
-    // Register pending middleware aliases
-    for (const { alias, handler } of (this._pendingMiddleware || [])) {
-      this._kernel.middleware(alias, handler);
-    }
-
-    // Register core providers (auto, unless disabled)
-    const coreProviders = this._buildCoreProviders();
-    this._kernel.providers([...coreProviders, ...this._userProviders]);
-
-    // Register routes
-    if (this._routesCb) {
-      this._kernel.routes(this._routesCb);
-    }
-
-    // Boot asynchronously
-    const self = this;
-    const boot = (async () => {
-      await self._kernel.boot();
-
-      if (!process.env.MILLAS_ROUTE_LIST) {
-        self._kernel.mountRoutes();
-
-        // Admin panel (mounted between routes and fallbacks)
-        if (self._adminOptions !== null) {
-          const adminOpts = typeof self._adminOptions === 'object'
-            ? self._adminOptions
-            : {};
-
-          try {
-            const Admin = require('../admin/Admin');
-            if (Object.keys(adminOpts).length) {
-              Admin.configure(adminOpts);
-            }
-            Admin.mount(self._expressApp);
-          } catch (err) {
-            process.stderr.write(`[millas] Admin mount failed: ${err.message}\n`);
-          }
-        }
-
-        self._kernel.mountFallbacks();
-
-        const onStart = self._options.onStart || null;
-        self._kernel.listen(undefined, undefined, onStart || undefined);
-      }
-
-      self._started = true;
-    })();
-
-    // Expose the promise for testing / programmatic use
-    this._bootPromise = boot;
-
-    return this;
-  }
-
-  /**
-   * Await the boot promise. Useful in tests or scripts.
+   * Usage (bootstrap/app.js):
+   *   module.exports = Millas.configure(__dirname)
+   *     .withAdmin()
+   *     .routes(Route => { ... })
+   *     .create();
    *
-   *   const app = await MillasApp.create().routes(...).start().ready();
+   * @param {string} basePath — pass __dirname from bootstrap/app.js
+   * @returns {MillasConfig}
    */
-  async ready() {
-    await (this._bootPromise || Promise.resolve());
-    return this;
-  }
-
-  // ─── Escape hatches ───────────────────────────────────────────────────────
-
-  /** The raw Express application instance. */
-  get express()    { return this._expressApp; }
-
-  /** The underlying Application kernel (also accessible as .app for back-compat). */
-  get kernel()     { return this._kernel; }
-  get app()        { return this._kernel; }
-
-  /** The DI container. */
-  get container()  { return this._kernel?._container; }
-
-  /** The Route instance — used by route:list command. */
-  get route()      { return this._kernel?._route; }
-
-  /**
-   * The raw Express app — backward-compatible alias.
-   * Allows: const { expressApp } = require('./bootstrap/app')
-   */
-  get expressApp() { return this._expressApp; }
-
-  // ─── Internal ─────────────────────────────────────────────────────────────
-
-  _buildCoreProviders() {
-    const opts = this._options;
-    const providers = [];
-
-    // Helper — require a provider, silently skip if not found
-    const load = (path) => {
-      try { return require(path); } catch { return null; }
-    };
-
-    // Logging — first so all other providers can use Log
-    if (opts.logging !== false) {
-      const p = load('../providers/LogServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Database
-    if (opts.database !== false) {
-      const p = load('../providers/DatabaseServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Cache + Storage
-    if (opts.cache !== false || opts.storage !== false) {
-      const p = load('../providers/CacheStorageServiceProvider');
-      if (p) {
-        if (opts.cache    !== false && p.CacheServiceProvider)   providers.push(p.CacheServiceProvider);
-        if (opts.storage  !== false && p.StorageServiceProvider) providers.push(p.StorageServiceProvider);
-      }
-    }
-
-    // Mail
-    if (opts.mail !== false) {
-      const p = load('../providers/MailServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Queue
-    if (opts.queue !== false) {
-      const p = load('../providers/QueueServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Events
-    if (opts.events !== false) {
-      const p = load('../providers/EventServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    return providers;
-  }
-}
+  configure(basePath) {
+    return new MillasConfig().configure(basePath);
+  },
+};
 
-module.exports = MillasApp;
+module.exports = Millas;

package/src/container/MillasConfig.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const AppInitializer = require("./AppInitializer");
+
+/**
+ * MillasConfig
+ *
+ * A pure config collector — no side effects, no HTTP, no booting.
+ * Every method returns `this` for chaining.
+ * The chain ends with .create() which seals the config into a MillasInstance.
+ *
+ * ── Usage (bootstrap/app.js) ─────────────────────────────────────────────────
+ *
+ *   const { Millas } = require('millas');
+ *
+ *   module.exports = Millas.config()
+ *     .providers([AppServiceProvider])
+ *     .routes(Route => {
+ *       require('../routes/web')(Route);
+ *       require('../routes/api')(Route);
+ *     })
+ *     .withAdmin()
+ *     .create();
+ */
+class MillasConfig {
+    constructor() {
+        this._config = {
+            // Absolute path to the project root — passed to all providers
+            // so they never need to call process.cwd() at runtime.
+            // Set via .configure(__dirname) in bootstrap/app.js.
+            basePath: null,
+
+            // Service providers
+            providers: [],
+
+            // Route registration callback: (Route) => void
+            routes: null,
+
+            // Named middleware aliases: [{ alias, handler }]
+            middleware: [],
+
+            // Core service toggles
+            logging:  true,
+            database: true,
+            auth:     true,   // AuthServiceProvider — always on by default
+            cache:    true,
+            storage:  true,
+            mail:     true,
+            queue:    true,
+            events:   true,
+
+            // Admin panel — null means disabled, {} or options object means enabled
+            admin: null,
+
+            // Raw adapter-level middleware (e.g. helmet, compression)
+            adapterMiddleware: [],
+
+            // Lifecycle callbacks
+            onStart: null,
+            onShutdown: null,
+        };
+    }
+
+    // ── Chainable config methods ───────────────────────────────────────────────
+
+    /**
+     * Set the application base path. Must be the first call.
+     * Pass __dirname from bootstrap/app.js — Laravel style.
+     *
+     *   Millas.configure(__dirname)
+     *
+     * All providers use this to locate config files, models, and routes
+     * without relying on process.cwd() at runtime.
+     *
+     * @param {string} basePath — absolute path to the project root
+     */
+    configure(basePath) {
+        this._config.basePath = basePath;
+        return this;
+    }
+
+    /**
+     * Register application service providers.
+     *
+     *   .providers([AppServiceProvider, PaymentServiceProvider])
+     */
+    providers(list = []) {
+        this._config.providers.push(...list);
+        return this;
+    }
+
+    /**
+     * Register application routes.
+     *
+     *   .routes(Route => {
+     *     require('../routes/web')(Route);
+     *     require('../routes/api')(Route);
+     *   })
+     */
+    routes(callback) {
+        this._config.routes = callback;
+        return this;
+    }
+
+    /**
+     * Register a named middleware alias.
+     *
+     *   .middleware('verified', EmailVerifiedMiddleware)
+     */
+    middleware(alias, handler) {
+        this._config.middleware.push({alias, handler});
+        return this;
+    }
+
+    /**
+     * Enable the admin panel.
+     *
+     * AuthServiceProvider and AdminServiceProvider are registered
+     * automatically — no need to add them to .providers([]).
+     *
+     *   .withAdmin()
+     *   .withAdmin({ prefix: '/cms', title: 'My CMS' })
+     *
+     * First-time setup:
+     *   millas migrate          # creates users + admin_log + sessions tables
+     *   millas createsuperuser  # creates your first admin user
+     */
+    withAdmin(options = {}) {
+        this._config.admin = options;
+        return this;
+    }
+
+    /**
+     * Disable individual core services.
+     *
+     *   .disable('mail', 'queue')
+     */
+    disable(...services) {
+        for (const svc of services) {
+            if (svc in this._config) this._config[svc] = false;
+        }
+        return this;
+    }
+
+    /**
+     * Apply raw adapter-level middleware (e.g. helmet, compression).
+     * These are applied before any Millas routes.
+     *
+     *   .use(helmet())
+     *   .use(compression())
+     */
+    use(...fns) {
+        this._config.adapterMiddleware.push(...fns);
+        return this;
+    }
+
+    /**
+     * Called once the server is listening.
+     *
+     *   .onStart((port, host) => console.log(`up on ${host}:${port}`))
+     */
+    onStart(fn) {
+        this._config.onStart = fn;
+        return this;
+    }
+
+    /**
+     * Called before graceful shutdown.
+     *
+     *   .onShutdown(async () => db.close())
+     */
+    onShutdown(fn) {
+        this._config.onShutdown = fn;
+        return this;
+    }
+
+    // ── Terminal method ────────────────────────────────────────────────────────
+
+    /**
+     *
+     *
+     *   module.exports = Millas.config()
+     *     .providers([AppServiceProvider])
+     *     .routes(...)
+     *     .create();
+     */
+    async create() {
+        return (new AppInitializer(Object.freeze({...this._config}))).boot();
+    }
+}
+
+module.exports = MillasConfig;

package/src/core/admin.js

@@ -0,0 +1,5 @@
+// ── Admin ─────────────────────────────────────────────────────────
+const {Admin, AdminResource, AdminField, AdminFilter, AdminHooks, AdminInline} = require('../admin');
+module.exports = {
+    Admin, AdminResource, AdminField, AdminFilter, AdminHooks, AdminInline
+}

package/src/core/auth.js

@@ -0,0 +1,9 @@
+const AuthUser = require("../auth/AuthUser");
+const JwtDriver = require("../auth/JwtDriver");
+const AuthMiddleware = require("../auth/AuthMiddleware");
+const RoleMiddleware = require("../auth/RoleMiddleware");
+const AuthController = require("../auth/AuthController");
+module.exports = {
+    AuthUser, JwtDriver, AuthMiddleware, RoleMiddleware,
+    AuthController,
+}