millas 0.1.0

package/src/commands/queue.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const chalk = require('chalk');
+const path  = require('path');
+const fs    = require('fs-extra');
+
+module.exports = function (program) {
+
+  program
+    .command('queue:work')
+    .description('Start the queue worker process')
+    .option('-q, --queue <queues>', 'Comma-separated queue names to process', 'default')
+    .option('-s, --sleep <seconds>', 'Seconds to sleep between polls', '3')
+    .option('--once', 'Process only one job then exit')
+    .action(async (options) => {
+      const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
+      if (!fs.existsSync(bootstrapPath)) {
+        console.error(chalk.red('\n  ✖ Not inside a Millas project.\n'));
+        process.exit(1);
+      }
+
+      const Queue       = require('../queue/Queue');
+      const QueueWorker = require('../queue/workers/QueueWorker');
+
+      // Boot the app to get config + job registry
+      process.env.MILLAS_ROUTE_LIST = 'true'; // suppress server listen
+      let app;
+      try {
+        const bootstrap = require(bootstrapPath);
+        app = bootstrap.app;
+      } catch (e) {
+        console.error(chalk.red(`\n  ✖ Failed to load app: ${e.message}\n`));
+        process.exit(1);
+      }
+
+      const queues  = options.queue.split(',').map(q => q.trim());
+      const sleep   = Number(options.sleep) || 3;
+      const maxJobs = options.once ? 1 : Infinity;
+
+      const worker = new QueueWorker(
+        Queue.getDriver(),
+        Queue.getRegistry(),
+        { queues, sleep, maxJobs }
+      );
+
+      await worker.start();
+    });
+
+  program
+    .command('queue:status')
+    .description('Show queue statistics')
+    .action(async () => {
+      const Queue = require('../queue/Queue');
+
+      let queueConfig;
+      try { queueConfig = require(path.resolve(process.cwd(), 'config/queue')); }
+      catch { queueConfig = { default: process.env.QUEUE_DRIVER || 'sync' }; }
+
+      Queue.configure(queueConfig);
+
+      console.log();
+      if (queueConfig.default === 'sync') {
+        console.log(chalk.yellow('  Queue driver: sync (jobs run immediately, no persistence)'));
+      } else {
+        const stats = await Queue.stats();
+        if (!stats || !stats.length) {
+          console.log(chalk.gray('  No jobs in queue.'));
+        } else {
+          console.log(chalk.bold('  Queue Statistics\n'));
+          for (const row of stats) {
+            const statusColor = row.status === 'completed' ? chalk.green
+              : row.status === 'failed' ? chalk.red
+              : chalk.yellow;
+            console.log(`  ${chalk.cyan(row.queue.padEnd(20))} ${statusColor(row.status.padEnd(12))} ${row.count}`);
+          }
+        }
+      }
+      console.log();
+      process.exit(0);
+    });
+
+  program
+    .command('queue:clear')
+    .description('Clear all pending jobs from a queue')
+    .option('-q, --queue <name>', 'Queue name to clear', 'default')
+    .action(async (options) => {
+      const Queue = require('../queue/Queue');
+      const n = await Queue.clear(options.queue);
+      console.log(chalk.green(`\n  ✔ Cleared ${n} job(s) from "${options.queue}" queue.\n`));
+      process.exit(0);
+    });
+};

package/src/commands/route.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const chalk = require('chalk');
+const path  = require('path');
+const fs    = require('fs-extra');
+
+module.exports = function (program) {
+  program
+    .command('route:list')
+    .description('List all registered routes')
+    .action(async () => {
+      const bootstrapPath = path.resolve(process.cwd(), 'bootstrap/app.js');
+
+      if (!fs.existsSync(bootstrapPath)) {
+        console.error(chalk.red('\n  ✖ Not inside a Millas project.\n'));
+        process.exit(1);
+      }
+
+      process.env.MILLAS_ROUTE_LIST = 'true';
+
+      let route;
+      try {
+        const bootstrap = require(bootstrapPath);
+        route = bootstrap.route;
+      } catch (err) {
+        console.error(chalk.red(`\n  ✖ Failed to load routes: ${err.message}\n`));
+        process.exit(1);
+      }
+
+      if (!route) {
+        console.log(chalk.yellow('\n  ⚠  Bootstrap did not export { route }.\n'));
+        process.exit(0);
+      }
+
+      const rows = route.list();
+
+      if (rows.length === 0) {
+        console.log(chalk.yellow('\n  No routes registered.\n'));
+        return;
+      }
+
+      console.log();
+      console.log(chalk.bold('  Registered Routes\n'));
+
+      const col = {
+        verb:    8,
+        path:    Math.max(6,  ...rows.map(r => r.path.length)) + 2,
+        handler: Math.max(8,  ...rows.map(r => formatHandler(r).length)) + 2,
+        mw:      Math.max(10, ...rows.map(r => (r.middleware || []).join(', ').length || 1)) + 2,
+      };
+
+      const header =
+        '  ' +
+        chalk.bold(pad('METHOD',     col.verb)) +
+        chalk.bold(pad('PATH',       col.path)) +
+        chalk.bold(pad('HANDLER',    col.handler)) +
+        chalk.bold(pad('MIDDLEWARE', col.mw)) +
+        chalk.bold('NAME');
+
+      console.log(header);
+      console.log(chalk.gray('  ' + '─'.repeat(col.verb + col.path + col.handler + col.mw + 10)));
+
+      for (const r of rows) {
+        const mw   = (r.middleware || []).join(', ') || chalk.gray('—');
+        const name = r.name || chalk.gray('—');
+        console.log(
+          '  ' +
+          verbChalk(r.verb)(pad(r.verb, col.verb)) +
+          chalk.cyan(pad(r.path, col.path)) +
+          chalk.white(pad(formatHandler(r), col.handler)) +
+          chalk.yellow(pad(mw, col.mw)) +
+          chalk.gray(name)
+        );
+      }
+
+      console.log(chalk.gray(`\n  ${rows.length} route(s) total.\n`));
+      process.exit(0);
+    });
+};
+
+function pad(str, len) { return String(str).padEnd(len); }
+
+function formatHandler(r) {
+  if (!r.handler) return '<none>';
+  if (typeof r.handler === 'function' && !r.method) return r.handler.name || '<closure>';
+  const name = r.handler.name || 'Controller';
+  return r.method ? `${name}@${r.method}` : name;
+}
+
+function verbChalk(verb) {
+  return { GET: chalk.green, POST: chalk.blue, PUT: chalk.yellow,
+           PATCH: chalk.magenta, DELETE: chalk.red }[verb] || chalk.white;
+}

package/src/commands/serve.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+
+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`));
+
+      process.env.MILLAS_PORT = options.port;
+      process.env.MILLAS_HOST = options.host;
+      process.env.NODE_ENV = process.env.NODE_ENV || 'development';
+
+      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);
+  }
+};

package/src/container/Application.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const Container        = require('./Container');
+const ProviderRegistry = require('../providers/ProviderRegistry');
+const { Route, Router, MiddlewareRegistry } = require('../router');
+const CorsMiddleware     = require('../middleware/CorsMiddleware');
+const ThrottleMiddleware = require('../middleware/ThrottleMiddleware');
+const LogMiddleware      = require('../middleware/LogMiddleware');
+const AuthMiddleware     = require('../auth/AuthMiddleware');
+
+/**
+ * Application
+ *
+ * The central Millas kernel. Owns:
+ *   - The DI container
+ *   - The provider registry
+ *   - The Express app
+ *   - The route instance
+ *   - The middleware registry
+ *
+ * Usage in bootstrap/app.js:
+ *
+ *   const { Application } = require('millas/src/container');
+ *   const app = new Application(expressApp);
+ *   app.providers([AppServiceProvider, DatabaseServiceProvider]);
+ *   await app.boot();
+ *   app.routes(route => {
+ *     require('../routes/web')(route);
+ *     require('../routes/api')(route);
+ *   });
+ *   app.mount();
+ *   app.listen();
+ */
+class Application {
+  constructor(expressApp) {
+    this._express   = expressApp;
+    this._container = new Container();
+    this._providers = new ProviderRegistry(this._container, expressApp);
+    this._mwRegistry = new MiddlewareRegistry();
+    this._route     = new Route();
+    this._booted    = false;
+
+    // Register core framework bindings
+    this._registerCoreBindings();
+  }
+
+  // ─── Configuration ───────────────────────────────────────────────────────────
+
+  /**
+   * Add service providers.
+   * @param {Array} providers
+   */
+  providers(providers = []) {
+    this._providers.addMany(providers);
+    return this;
+  }
+
+  /**
+   * Register a middleware alias.
+   *
+   * app.middleware('auth', AuthMiddleware)
+   * app.middleware('throttle', new ThrottleMiddleware({ max: 60 }))
+   */
+  middleware(alias, handler) {
+    this._mwRegistry.register(alias, handler);
+    return this;
+  }
+
+  /**
+   * Define all routes via a callback.
+   *
+   * app.routes(route => {
+   *   require('../routes/web')(route);
+   *   require('../routes/api')(route);
+   * });
+   */
+  routes(callback) {
+    callback(this._route);
+    return this;
+  }
+
+  // ─── Lifecycle ───────────────────────────────────────────────────────────────
+
+  /**
+   * Run the full provider register → boot lifecycle.
+   */
+  async boot() {
+    if (this._booted) return this;
+    await this._providers.boot();
+    this._booted = true;
+    return this;
+  }
+
+  /**
+   * Bind all routes onto the Express app + mount error handlers.
+   */
+  mount() {
+    const router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
+    router.mount();
+    return this;
+  }
+
+  /**
+   * Start the HTTP server.
+   */
+  listen(port, host, callback) {
+    const _port = port || parseInt(process.env.APP_PORT, 10) || 3000;
+    const _host = host || process.env.MILLAS_HOST || 'localhost';
+
+    this._express.listen(_port, _host, () => {
+      if (!process.env.MILLAS_ROUTE_LIST) {
+        const routeCount = this._route.list().length;
+        console.log(`\n  ⚡ Millas running at http://${_host}:${_port}`);
+        console.log(`  ${routeCount} route(s) registered\n`);
+      }
+      if (typeof callback === 'function') callback(_port, _host);
+    });
+
+    return this;
+  }
+
+  // ─── Container Proxy ─────────────────────────────────────────────────────────
+
+  /**
+   * Bind a transient into the container.
+   */
+  bind(abstract, concrete) {
+    this._container.bind(abstract, concrete);
+    return this;
+  }
+
+  /**
+   * Bind a singleton into the container.
+   */
+  singleton(abstract, concrete) {
+    this._container.singleton(abstract, concrete);
+    return this;
+  }
+
+  /**
+   * Register a pre-built instance.
+   */
+  instance(abstract, value) {
+    this._container.instance(abstract, value);
+    return this;
+  }
+
+  /**
+   * Resolve something from the container.
+   */
+  make(abstract, overrides) {
+    return this._container.make(abstract, overrides);
+  }
+
+  // ─── Accessors ───────────────────────────────────────────────────────────────
+
+  get container()    { return this._container; }
+  get route()        { return this._route; }
+  get express()      { return this._express; }
+  get mwRegistry()   { return this._mwRegistry; }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  _registerCoreBindings() {
+    // Register the application itself
+    this._container.instance('app',       this);
+    this._container.instance('container', this._container);
+
+    // Register built-in middleware
+    this._mwRegistry.register('cors',     new CorsMiddleware());
+    this._mwRegistry.register('throttle', new ThrottleMiddleware({ max: 60, window: 60 }));
+    this._mwRegistry.register('log',      new LogMiddleware());
+    this._mwRegistry.register('auth',     AuthMiddleware);
+  }
+}
+
+module.exports = Application;

package/src/container/Container.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/**
+ * Container
+ *
+ * Millas dependency injection container.
+ *
+ * Three binding types:
+ *
+ *   container.bind('UserService', UserService)
+ *     — fresh instance each time make() is called
+ *
+ *   container.singleton('DB', DatabaseService)
+ *     — same instance returned on every make()
+ *
+ *   container.instance('Config', configObject)
+ *     — register a pre-built value or object directly
+ *
+ * Auto-resolution:
+ *   If a class constructor lists dependencies by name in a static
+ *   `inject` array, the container resolves them automatically:
+ *
+ *   class OrderService {
+ *     static inject = ['UserService', 'PaymentService'];
+ *     constructor(userService, paymentService) { ... }
+ *   }
+ *
+ *   container.bind('OrderService', OrderService);
+ *   const svc = container.make('OrderService');
+ *   // UserService and PaymentService injected automatically
+ */
+class Container {
+  constructor() {
+    this._bindings   = new Map();   // abstract → { concrete, type }
+    this._resolved   = new Map();   // abstract → instance  (singletons)
+    this._aliases    = new Map();   // alias    → abstract
+    this._tags       = new Map();   // tag      → [abstract, ...]
+    this._resolving  = new Set();   // circular dependency guard
+  }
+
+  // ─── Registration ────────────────────────────────────────────────────────────
+
+  /**
+   * Bind an abstract name to a concrete class or factory.
+   * A new instance is created every time make() is called.
+   *
+   * container.bind('UserService', UserService)
+   * container.bind('Logger', () => new Logger({ level: 'debug' }))
+   */
+  bind(abstract, concrete) {
+    this._bindings.set(abstract, { concrete, type: 'transient' });
+    // Clear any resolved singleton if re-bound
+    this._resolved.delete(abstract);
+    return this;
+  }
+
+  /**
+   * Bind as a singleton — the same instance is returned on every make().
+   *
+   * container.singleton('DB', DatabaseService)
+   */
+  singleton(abstract, concrete) {
+    this._bindings.set(abstract, { concrete, type: 'singleton' });
+    this._resolved.delete(abstract);
+    return this;
+  }
+
+  /**
+   * Register a pre-built value directly.
+   * make() always returns this exact value.
+   *
+   * container.instance('Config', { port: 3000 })
+   * container.instance('App', expressApp)
+   */
+  instance(abstract, value) {
+    this._bindings.set(abstract, { concrete: null, type: 'instance' });
+    this._resolved.set(abstract, value);
+    return this;
+  }
+
+  /**
+   * Register an alias for an abstract name.
+   *
+   * container.alias('db', 'DatabaseService')
+   * container.make('db') // resolves DatabaseService
+   */
+  alias(alias, abstract) {
+    this._aliases.set(alias, abstract);
+    return this;
+  }
+
+  /**
+   * Tag multiple bindings under a group name.
+   *
+   * container.tag(['MySQLDriver', 'SQLiteDriver'], 'db.drivers')
+   * container.tagged('db.drivers') // → [MySQLDriver instance, SQLiteDriver instance]
+   */
+  tag(abstracts, tag) {
+    if (!this._tags.has(tag)) this._tags.set(tag, []);
+    for (const a of [].concat(abstracts)) {
+      this._tags.get(tag).push(a);
+    }
+    return this;
+  }
+
+  // ─── Resolution ──────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve a binding by name, building and injecting dependencies.
+   *
+   * const svc = container.make('UserService')
+   * const svc = container.make(UserService)   // class reference also works
+   */
+  make(abstract, overrides = {}) {
+    // Accept class references directly
+    if (typeof abstract === 'function') {
+      return this._build(abstract, overrides);
+    }
+
+    // Resolve alias
+    const resolved = this._aliases.get(abstract) || abstract;
+
+    // Guard against circular deps
+    if (this._resolving.has(resolved)) {
+      throw new Error(
+        `Circular dependency detected while resolving "${resolved}".`
+      );
+    }
+
+    const binding = this._bindings.get(resolved);
+
+    if (!binding) {
+      throw new Error(
+        `"${resolved}" is not bound in the container. ` +
+        `Did you forget to call container.bind('${resolved}', MyClass)?`
+      );
+    }
+
+    // Pre-built instance
+    if (binding.type === 'instance') {
+      return this._resolved.get(resolved);
+    }
+
+    // Return cached singleton
+    if (binding.type === 'singleton' && this._resolved.has(resolved)) {
+      return this._resolved.get(resolved);
+    }
+
+    this._resolving.add(resolved);
+    let instance;
+
+    try {
+      instance = this._build(binding.concrete, overrides);
+    } finally {
+      this._resolving.delete(resolved);
+    }
+
+    if (binding.type === 'singleton') {
+      this._resolved.set(resolved, instance);
+    }
+
+    return instance;
+  }
+
+  /**
+   * Resolve all bindings under a tag.
+   *
+   * const drivers = container.tagged('db.drivers')
+   */
+  tagged(tag) {
+    const abstracts = this._tags.get(tag);
+    if (!abstracts) return [];
+    return abstracts.map(a => this.make(a));
+  }
+
+  /**
+   * Check whether a name is bound.
+   */
+  has(abstract) {
+    const resolved = this._aliases.get(abstract) || abstract;
+    return this._bindings.has(resolved);
+  }
+
+  /**
+   * Call a method or function, auto-injecting its declared dependencies.
+   *
+   * container.call(myService, 'processOrder', { orderId: 123 })
+   * container.call(myFunction)
+   */
+  call(target, method, extras = {}) {
+    if (typeof target === 'function') {
+      return this._callFunction(target, extras);
+    }
+    if (typeof target === 'object' && typeof target[method] === 'function') {
+      return this._callFunction(target[method].bind(target), extras);
+    }
+    throw new Error(`Cannot call "${method}" on the given target.`);
+  }
+
+  /**
+   * Forget a resolved singleton (force re-instantiation on next make()).
+   */
+  forgetInstance(abstract) {
+    this._resolved.delete(abstract);
+    return this;
+  }
+
+  /**
+   * Remove a binding entirely.
+   */
+  unbind(abstract) {
+    this._bindings.delete(abstract);
+    this._resolved.delete(abstract);
+    return this;
+  }
+
+  /**
+   * List all registered abstract names.
+   */
+  bindings() {
+    return [...this._bindings.keys()];
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  /**
+   * Build a concrete class or factory, resolving its inject[] dependencies.
+   */
+  _build(concrete, overrides = {}) {
+    if (concrete === null || concrete === undefined) {
+      throw new Error('Cannot build a null concrete.');
+    }
+
+    // Factory function (not a class constructor)
+    if (this._isFactory(concrete)) {
+      return concrete(this, overrides);
+    }
+
+    // Class — resolve static inject[] array
+    const deps = this._resolveDependencies(concrete, overrides);
+    return new concrete(...deps);
+  }
+
+  /**
+   * Resolve the inject[] static array on a class.
+   *
+   * class MyService {
+   *   static inject = ['Logger', 'Config'];
+   * }
+   */
+  _resolveDependencies(Cls, overrides = {}) {
+    const inject = Cls.inject || [];
+    return inject.map(dep => {
+      if (dep in overrides) return overrides[dep];
+      return this.make(dep);
+    });
+  }
+
+  /**
+   * Detect whether `fn` is a plain factory function vs a class constructor.
+   * Heuristic: class constructors start with an uppercase letter.
+   */
+  _isFactory(fn) {
+    if (typeof fn !== 'function') return false;
+    const str = fn.toString();
+    // Arrow functions and non-class functions = factory
+    if (str.startsWith('class ')) return false;
+    if (/^function\s+[A-Z]/.test(str)) return false; // old-style class
+    // Check if it's a regular function (not a constructor-style)
+    const name = fn.name || '';
+    return !(name[0] && name[0] === name[0].toUpperCase() && name[0] !== name[0].toLowerCase());
+  }
+
+  _callFunction(fn, extras = {}) {
+    const inject = fn.inject || [];
+    const deps   = inject.map(dep => dep in extras ? extras[dep] : this.make(dep));
+    return fn(...deps);
+  }
+}
+
+module.exports = Container;

package/src/container/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const Container        = require('./Container');
+const Application      = require('./Application');
+const ServiceProvider  = require('../providers/ServiceProvider');
+const ProviderRegistry = require('../providers/ProviderRegistry');
+
+module.exports = {
+  Container,
+  Application,
+  ServiceProvider,
+  ProviderRegistry,
+};