millas 0.1.0

package/src/router/Route.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const RouteGroup = require('./RouteGroup');
+const RouteRegistry = require('./RouteRegistry');
+
+/**
+ * Route
+ *
+ * The primary developer-facing API for defining routes.
+ *
+ * Usage:
+ *   Route.get('/users', UserController, 'index')
+ *   Route.post('/users', UserController, 'store')
+ *   Route.resource('/users', UserController)
+ *   Route.group({ prefix: '/api', middleware: ['auth'] }, () => { ... })
+ *   Route.prefix('/v1').group(() => { ... })
+ */
+class Route {
+  constructor() {
+    this._registry = new RouteRegistry();
+    this._groupStack = [];   // stack of active group contexts
+  }
+
+  // ─── HTTP Verbs ─────────────────────────────────────────────────────────────
+
+  get(path, handler, method) {
+    return this._add('GET', path, handler, method);
+  }
+
+  post(path, handler, method) {
+    return this._add('POST', path, handler, method);
+  }
+
+  put(path, handler, method) {
+    return this._add('PUT', path, handler, method);
+  }
+
+  patch(path, handler, method) {
+    return this._add('PATCH', path, handler, method);
+  }
+
+  delete(path, handler, method) {
+    return this._add('DELETE', path, handler, method);
+  }
+
+  options(path, handler, method) {
+    return this._add('OPTIONS', path, handler, method);
+  }
+
+  any(path, handler, method) {
+    const verbs = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+    verbs.forEach(v => this._add(v, path, handler, method));
+  }
+
+  // ─── Resource Routes ─────────────────────────────────────────────────────────
+  // Generates 5 conventional RESTful routes for a controller.
+
+  resource(path, ControllerClass, options = {}) {
+    const only   = options.only;
+    const except = options.except || [];
+
+    const map = [
+      { verb: 'GET',    suffix: '',       action: 'index',   name: `${path}.index`   },
+      { verb: 'GET',    suffix: '/:id',   action: 'show',    name: `${path}.show`    },
+      { verb: 'POST',   suffix: '',       action: 'store',   name: `${path}.store`   },
+      { verb: 'PUT',    suffix: '/:id',   action: 'update',  name: `${path}.update`  },
+      { verb: 'DELETE', suffix: '/:id',   action: 'destroy', name: `${path}.destroy` },
+    ];
+
+    for (const route of map) {
+      if (only && !only.includes(route.action)) continue;
+      if (except.includes(route.action)) continue;
+      this._add(route.verb, path + route.suffix, ControllerClass, route.action, route.name);
+    }
+
+    return this;
+  }
+
+  // ─── Route Groups ────────────────────────────────────────────────────────────
+
+  /**
+   * Route.group({ prefix, middleware, name }, callback)
+   * Route.group(callback)  — shorthand, no attributes
+   */
+  group(attributes, callback) {
+    if (typeof attributes === 'function') {
+      callback = attributes;
+      attributes = {};
+    }
+
+    const group = new RouteGroup(attributes, this._groupStack);
+    this._groupStack.push(group);
+    callback();
+    this._groupStack.pop();
+
+    return this;
+  }
+
+  /**
+   * Fluent prefix() — returns a builder that defers to group()
+   *   Route.prefix('/api/v1').middleware(['auth']).group(() => { ... })
+   */
+  prefix(prefix) {
+    return new RouteGroupBuilder(this, { prefix });
+  }
+
+  /**
+   * Attach middleware to the next group or route
+   */
+  middleware(middleware) {
+    return new RouteGroupBuilder(this, { middleware });
+  }
+
+  /**
+   * Named route prefix
+   */
+  name(name) {
+    return new RouteGroupBuilder(this, { name });
+  }
+
+  // ─── Auth convenience ────────────────────────────────────────────────────────
+
+  /**
+   * Register all standard auth routes under a given prefix.
+   *
+   * Route.auth()              // registers under /auth
+   * Route.auth('/api/auth')   // custom prefix
+   *
+   * Registers:
+   *   POST   /auth/register
+   *   POST   /auth/login
+   *   POST   /auth/logout
+   *   GET    /auth/me
+   *   POST   /auth/refresh
+   *   POST   /auth/forgot-password
+   *   POST   /auth/reset-password
+   */
+  auth(prefix = '/auth') {
+    const AuthController = require('../auth/AuthController');
+    this.group({ prefix }, () => {
+      this.post('/register',        AuthController, 'register');
+      this.post('/login',           AuthController, 'login');
+      this.post('/logout',          AuthController, 'logout');
+      this.get('/me',               AuthController, 'me');
+      this.post('/refresh',         AuthController, 'refresh');
+      this.post('/forgot-password', AuthController, 'forgotPassword');
+      this.post('/reset-password',  AuthController, 'resetPassword');
+    });
+    return this;
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  _add(verb, path, handler, method, routeName) {
+    // Merge active group context
+    const context = this._mergeGroupStack();
+
+    // Build full path
+    const fullPath = this._joinPaths(context.prefix || '', path);
+
+    // Resolve middleware
+    const middleware = [
+      ...(context.middleware || []),
+    ];
+
+    // Build route name
+    const name = routeName
+      ? (context.name ? context.name + '.' + routeName : routeName)
+      : null;
+
+    const entry = {
+      verb,
+      path: fullPath,
+      handler,
+      method,      // string method name OR raw function
+      middleware,
+      name,
+    };
+
+    this._registry.register(entry);
+    return this;
+  }
+
+  _mergeGroupStack() {
+    return this._groupStack.reduce((merged, group) => {
+      // Prefix: concatenate
+      merged.prefix = this._joinPaths(merged.prefix || '', group.prefix || '');
+      // Middleware: accumulate
+      merged.middleware = [
+        ...(merged.middleware || []),
+        ...(group.middleware || []),
+      ];
+      // Name: concatenate
+      merged.name = [merged.name, group.name].filter(Boolean).join('');
+      return merged;
+    }, {});
+  }
+
+  _joinPaths(...parts) {
+    return '/' + parts
+      .map(p => p.replace(/^\/|\/$/g, ''))
+      .filter(Boolean)
+      .join('/');
+  }
+
+  // ─── Public Accessors ────────────────────────────────────────────────────────
+
+  getRegistry() {
+    return this._registry;
+  }
+
+  list() {
+    return this._registry.all();
+  }
+}
+
+// ─── RouteGroupBuilder (fluent chain) ────────────────────────────────────────
+
+class RouteGroupBuilder {
+  constructor(router, attrs) {
+    this._router = router;
+    this._attrs  = attrs;
+  }
+
+  prefix(prefix) {
+    this._attrs.prefix = this._joinPaths(this._attrs.prefix || '', prefix);
+    return this;
+  }
+
+  middleware(middleware) {
+    this._attrs.middleware = [
+      ...(this._attrs.middleware || []),
+      ...(Array.isArray(middleware) ? middleware : [middleware]),
+    ];
+    return this;
+  }
+
+  name(name) {
+    this._attrs.name = (this._attrs.name || '') + name;
+    return this;
+  }
+
+  group(callback) {
+    return this._router.group(this._attrs, callback);
+  }
+
+  _joinPaths(...parts) {
+    return '/' + parts
+      .map(p => p.replace(/^\/|\/$/g, ''))
+      .filter(Boolean)
+      .join('/');
+  }
+}
+
+module.exports = Route;

package/src/router/RouteGroup.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * RouteGroup
+ *
+ * Represents a single group context pushed onto the group stack.
+ * Holds prefix, middleware array, and name prefix for the group.
+ */
+class RouteGroup {
+  constructor(attributes = {}) {
+    this.prefix     = attributes.prefix     || '';
+    this.middleware = Array.isArray(attributes.middleware)
+      ? attributes.middleware
+      : (attributes.middleware ? [attributes.middleware] : []);
+    this.name       = attributes.name       || '';
+  }
+}
+
+module.exports = RouteGroup;

package/src/router/RouteRegistry.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * RouteRegistry
+ *
+ * Central store for all registered routes.
+ * Used by the Router to bind to Express, and by `millas route:list`.
+ */
+class RouteRegistry {
+  constructor() {
+    this._routes = [];
+    this._namedRoutes = {};
+  }
+
+  register(entry) {
+    this._routes.push(entry);
+
+    if (entry.name) {
+      this._namedRoutes[entry.name] = entry;
+    }
+  }
+
+  all() {
+    return [...this._routes];
+  }
+
+  findByName(name) {
+    return this._namedRoutes[name] || null;
+  }
+
+  findByPath(verb, path) {
+    return this._routes.find(
+      r => r.verb === verb.toUpperCase() && r.path === path
+    ) || null;
+  }
+
+  /**
+   * Return a formatted table for `millas route:list`
+   */
+  toTable() {
+    return this._routes.map(r => ({
+      Method:     r.verb.padEnd(7),
+      Path:       r.path,
+      Handler:    r.handler
+        ? (typeof r.handler === 'function'
+            ? r.handler.name || '<closure>'
+            : (r.handler.name || r.handler.toString()) + (r.method ? `@${r.method}` : ''))
+        : '<none>',
+      Middleware: (r.middleware || []).join(', ') || '—',
+      Name:       r.name || '—',
+    }));
+  }
+}
+
+module.exports = RouteRegistry;

package/src/router/Router.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const MiddlewareRegistry = require('./MiddlewareRegistry');
+
+/**
+ * Router
+ *
+ * Takes a populated RouteRegistry and binds every route
+ * onto a live Express app instance.
+ *
+ * Also wraps async controller methods so unhandled promise
+ * rejections are forwarded to Express error handlers.
+ */
+class Router {
+  /**
+   * @param {object} expressApp   — the Express application
+   * @param {RouteRegistry} registry
+   * @param {MiddlewareRegistry} middlewareRegistry
+   */
+  constructor(expressApp, registry, middlewareRegistry) {
+    this._app      = expressApp;
+    this._registry = registry;
+    this._mw       = middlewareRegistry || new MiddlewareRegistry();
+  }
+
+  /**
+   * Bind all registered routes onto the Express app.
+   */
+  mount() {
+    const routes = this._registry.all();
+
+    for (const route of routes) {
+      this._bindRoute(route);
+    }
+
+    // Mount 404 handler after all routes
+    this._app.use((req, res) => {
+      res.status(404).json({
+        error:   'Not Found',
+        message: `Cannot ${req.method} ${req.path}`,
+        status:  404,
+      });
+    });
+
+    // Mount global error handler
+    this._app.use((err, req, res, _next) => {
+      const status  = err.status || err.statusCode || 500;
+      const message = err.message || 'Internal Server Error';
+
+      if (status >= 500 && process.env.NODE_ENV !== 'production') {
+        console.error(err.stack);
+      }
+
+      res.status(status).json({
+        error:   status >= 500 ? 'Internal Server Error' : message,
+        message,
+        status,
+        // Validation errors (HttpError with errors field)
+        ...(err.errors  && { errors: err.errors }),
+        // Stack trace in development for 5xx only
+        ...(status >= 500 && process.env.NODE_ENV !== 'production' && { stack: err.stack }),
+      });
+    });
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  _bindRoute(route) {
+    const verb    = route.verb.toLowerCase();
+    const path    = route.path;
+
+    // Resolve middleware chain
+    const mwHandlers = this._resolveMiddleware(route.middleware || []);
+
+    // Resolve the terminal handler
+    const terminal = this._resolveHandler(route.handler, route.method);
+
+    // Register on Express: app.get(path, [...mw], handler)
+    this._app[verb](path, ...mwHandlers, terminal);
+  }
+
+  _resolveMiddleware(list) {
+    return list.map(alias => {
+      try {
+        return this._mw.resolve(alias);
+      } catch (err) {
+        console.warn(`[Millas] Warning: ${err.message} — skipping.`);
+        return (_req, _res, next) => next();
+      }
+    });
+  }
+
+  _resolveHandler(handler, method) {
+    // Case 1: raw async/sync function
+    if (typeof handler === 'function' && !method) {
+      return this._wrapAsync(handler);
+    }
+
+    // Case 2: controller class + method name string
+    if (typeof handler === 'function' && typeof method === 'string') {
+      const instance = new handler();
+      if (typeof instance[method] !== 'function') {
+        throw new Error(
+          `Method "${method}" not found on controller "${handler.name}".`
+        );
+      }
+      return this._wrapAsync(instance[method].bind(instance));
+    }
+
+    // Case 3: already-instantiated object + method name
+    if (typeof handler === 'object' && handler !== null && typeof method === 'string') {
+      if (typeof handler[method] !== 'function') {
+        throw new Error(`Method "${method}" not found on handler object.`);
+      }
+      return this._wrapAsync(handler[method].bind(handler));
+    }
+
+    // Case 4: plain object/function with no method (fallback)
+    if (typeof handler === 'function') {
+      return this._wrapAsync(handler);
+    }
+
+    throw new Error(`Invalid route handler: ${JSON.stringify(handler)}`);
+  }
+
+  /**
+   * Wrap an async function so rejections are forwarded to next(err).
+   * Sync functions pass through unchanged.
+   */
+  _wrapAsync(fn) {
+    if (fn.constructor.name === 'AsyncFunction') {
+      return (req, res, next) => fn(req, res, next).catch(next);
+    }
+    return fn;
+  }
+}
+
+module.exports = Router;

package/src/router/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const Route              = require('./Route');
+const Router             = require('./Router');
+const RouteRegistry      = require('./RouteRegistry');
+const RouteGroup         = require('./RouteGroup');
+const MiddlewareRegistry = require('./MiddlewareRegistry');
+
+module.exports = {
+  Route,
+  Router,
+  RouteRegistry,
+  RouteGroup,
+  MiddlewareRegistry,
+};

package/src/scaffold/generator.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { getProjectFiles } = require('./templates');
+
+/**
+ * Generates a full Millas project at the given targetDir.
+ */
+async function generateProject(projectName, targetDir) {
+  const files = getProjectFiles(projectName);
+
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, filePath);
+    await fs.ensureDir(path.dirname(fullPath));
+    await fs.writeFile(fullPath, content, 'utf8');
+  }
+
+  // Create empty directories that need to exist but have no initial files
+  const emptyDirs = [
+    'storage/logs',
+    'storage/uploads',
+    'database/migrations',
+    'database/seeders',
+    'tests',
+  ];
+
+  for (const dir of emptyDirs) {
+    await fs.ensureDir(path.join(targetDir, dir));
+    await fs.writeFile(path.join(targetDir, dir, '.gitkeep'), '', 'utf8');
+  }
+}
+
+module.exports = { generateProject };