kaelum 1.2.0 → 1.3.0

package/cli/templates/web/app.js

@@ -1,15 +1,26 @@
+// app.js - example project generated by Kaelum (Web template)
 const kaelum = require("kaelum");
+
 const app = kaelum();
 
-// SetConfig para aplicar configurações de segurança e middlewares
+// Enable basic security + static serving via setConfig (uses Kaelum internals)
 app.setConfig({
   cors: true,
   helmet: true,
+  static: "public", // will serve ./public
+  bodyParser: true, // default enabled — explicit for clarity
 });
 
-// Importa e registra as rotas
+// Register routes (routes.js uses Kaelum helpers)
 const routes = require("./routes");
 routes(app);
 
-// Inicia o servidor
-app.start(3000);
+// optional: health check endpoint
+app.healthCheck("/health");
+
+// install Kaelum default error handler (returns JSON on errors)
+app.useErrorHandler({ exposeStack: false });
+
+// Start server (explicit port for template demo)
+const PORT = process.env.PORT || 3000;
+app.start(PORT);

package/cli/templates/web/middlewares/logger.js

@@ -1,6 +1,6 @@
-function logger(req, res, next) {
-  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
+// example middleware: simple request logger
+module.exports = function (req, res, next) {
+  const now = new Date();
+  console.log(`[${now.toISOString()}] ${req.method} ${req.originalUrl}`);
   next();
-}
-
-module.exports = logger;
+};

package/cli/templates/web/package.json

@@ -1,13 +1,23 @@
 {
-  "name": "my-web-app",
-  "version": "1.0.0",
-  "description": "Project generated with Kaelum framework.",
-  "main": "app.js",
+  "name": "kaelum-web-app",
+  "version": "0.1.0",
+  "description": "Exemplo de app gerado pela CLI Kaelum (web template)",
   "scripts": {
-    "start": "node app.js"
+    "start": "node app.js",
+    "dev": "nodemon app.js"
   },
+  "keywords": [
+    "kaelum",
+    "web"
+  ],
+  "author": "",
+  "license": "MIT",
   "dependencies": {
-    "kaelum": "^1.1.0"
+    "kaelum": "^1.3.0",
+    "cors": "^2.8.5",
+    "helmet": "^6.0.0"
   },
-  "license": "MIT"
+  "devDependencies": {
+    "nodemon": "^2.0.22"
+  }
 }

package/cli/templates/web/public/style.css

@@ -1,54 +1,61 @@
+:root {
+  --bg: #f6fbff;
+  --card: #ffffff;
+  --accent: #6fa8dc;
+  --text: #243746;
+  --muted: #6b7a86;
+}
+
+* {
+  box-sizing: border-box;
+}
 body {
   margin: 0;
-  font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
-  background-color: #f9f9f9;
-  color: #333;
+  font-family: Inter, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial;
+  background: var(--bg);
+  color: var(--text);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
 }
 
 .container {
-  padding: 40px;
-  max-width: 800px;
-  margin: 0 auto;
-  text-align: center;
-}
-
-h1 {
-  font-size: 2.5rem;
-  margin-bottom: 10px;
-  color: #4a90e2;
+  max-width: 900px;
+  margin: 48px auto;
+  padding: 24px;
 }
 
-p {
-  font-size: 1.1rem;
-  margin-bottom: 30px;
+header h1 {
+  margin: 0;
+  color: var(--accent);
+  font-size: 2.1rem;
 }
 
-.info {
-  background-color: #fff;
-  padding: 20px;
-  border-radius: 8px;
-  box-shadow: 0 0 10px rgba(0, 0, 0, 0.05);
+.subtitle {
+  margin: 6px 0 18px 0;
+  color: var(--muted);
 }
 
-ul {
-  list-style-type: none;
-  padding: 0;
+.content {
+  margin-top: 18px;
 }
 
-li {
-  text-align: left;
-  margin-bottom: 10px;
+.cards {
+  display: flex;
+  gap: 16px;
+  margin-top: 12px;
 }
 
-code {
-  background-color: #eee;
-  padding: 2px 6px;
-  border-radius: 4px;
-  font-family: monospace;
+.card {
+  background: var(--card);
+  border-radius: 8px;
+  padding: 16px;
+  box-shadow: 0 6px 18px rgba(37, 57, 99, 0.06);
+  flex: 1;
 }
 
-footer {
-  margin-top: 40px;
+.small {
+  margin-top: 20px;
+  color: var(--muted);
   font-size: 0.9rem;
-  color: #999;
 }

package/cli/templates/web/routes.js

@@ -1,27 +1,32 @@
-const logger = require("./middlewares/logger");
+// routes.js - example route declarations using Kaelum API
+const path = require("path");
 
-function Routes(app) {
+module.exports = function (app) {
+  // Home: serve the index.html from /views
   app.addRoute("/", {
     get: (req, res) => {
-      res.sendFile("views/index.html", { root: __dirname });
+      // send the static HTML file from the views folder
+      res.sendFile(path.join(process.cwd(), "views", "index.html"));
     },
-    post: (req, res) => res.send("POST: Dados recebidos na página inicial."),
   });
 
+  // About page - simple text
   app.addRoute("/about", {
-    get: (req, res) => res.send("About page"),
+    get: (req, res) => {
+      res.send("About Kaelum — a minimal framework scaffolded by the CLI.");
+    },
   });
 
-  // Rota "/secure" com middleware aplicado diretamente
-  app.addRoute("/secure", {
-    get: [
-      logger,
-      (req, res) => {
-        res.send("GET: Área segura! Middleware foi executado.");
-      },
-    ],
-  });
-  
-}
+  // Example route using per-path middleware (logger)
+  // The middleware is mounted on '/protected' and the route uses it.
+  const logger = require("./middlewares/logger");
+  app.setMiddleware("/protected", logger);
 
-module.exports = Routes;
+  app.addRoute("/protected", {
+    get: (req, res) => {
+      res.send(
+        "This route is protected by a simple request logger middleware."
+      );
+    },
+  });
+};

package/cli/templates/web/views/index.html

@@ -1,25 +1,45 @@
-<html lang="en">
+<!DOCTYPE html>
+<html lang="pt-BR">
   <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Kaelum.js - Welcome</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Kaelum — Hello</title>
     <link rel="stylesheet" href="/style.css" />
   </head>
   <body>
-    <div class="container">
-      <h1>🚀 Welcome to Kaelum.js</h1>
-      <p>Your minimalist framework to build APIs and web pages easily.</p>
-      <div class="info">
-        <h2>🧭 Start exploring</h2>
-        <ul>
-          <li><strong>Global Middlewares:</strong> See <code>app.js</code></li>
-          <li><strong>Routing:</strong> Edit <code>routes.js</code></li>
-          <li><strong>Static Files:</strong> Inside <code>public/</code></li>
-        </ul>
-      </div>
-      <footer>
-        <p>Made with ❤️ using Kaelum.js</p>
-      </footer>
-    </div>
+    <main class="container">
+      <header>
+        <h1>Kaelum.js</h1>
+        <p class="subtitle">
+          Framework simplificada para Web e APIs — Template de demonstração
+        </p>
+      </header>
+
+      <section class="content">
+        <h2>Bem-vindo(a) 👋</h2>
+        <p>
+          Este é um template gerado automaticamente pela CLI do
+          <strong>Kaelum</strong>.
+        </p>
+
+        <div class="cards">
+          <div class="card">
+            <h3>Rotas</h3>
+            <p>
+              Veja as rotas: <code>/</code>, <code>/about</code>,
+              <code>/protected</code>, <code>/health</code>.
+            </p>
+          </div>
+          <div class="card">
+            <h3>Segurança</h3>
+            <p>CORS e Helmet foram ativados via <code>app.setConfig</code>.</p>
+          </div>
+        </div>
+
+        <p class="small">
+          Gerado pela Kaelum CLI • Versão do template para Kaelum ^1.3.0
+        </p>
+      </section>
+    </main>
   </body>
 </html>

package/cli/utils.js

@@ -1,12 +1,58 @@
 const fs = require("fs-extra");
 const path = require("path");
 
-async function copyTemplate(sourceDir, targetDir) {
+/**
+ * Copy a template directory to target and update package.json with projectName.
+ * @param {string} sourceDir
+ * @param {string} targetDir
+ * @param {string} projectName (optional) - will override package.json name if present
+ */
+async function copyTemplate(sourceDir, targetDir, projectName) {
   try {
-    await fs.copy(sourceDir, targetDir);
+    if (!sourceDir || !targetDir) {
+      throw new Error("Source and target directories are required.");
+    }
+
+    // ensure source exists
+    const exists = await fs.pathExists(sourceDir);
+    if (!exists) {
+      throw new Error(`Template not found: ${sourceDir}`);
+    }
+
+    // copy
+    await fs.copy(sourceDir, targetDir, {
+      overwrite: false,
+      errorOnExist: true,
+    });
+
+    // try update package.json in the copied template
+    const pkgPath = path.join(targetDir, "package.json");
+    const pkgExists = await fs.pathExists(pkgPath);
+    if (pkgExists && projectName) {
+      try {
+        const raw = await fs.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        // set sensible defaults for created project
+        pkg.name = projectName;
+        if (!pkg.version) pkg.version = "0.1.0";
+        if (!pkg.description)
+          pkg.description = `${projectName} - generated by Kaelum CLI`;
+        // ensure type commonjs by default for templates that expect require/module.exports
+        if (!pkg.type) pkg.type = "commonjs";
+        await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2), "utf8");
+      } catch (e) {
+        // non-fatal: warn but continue
+        console.warn(
+          "Warning: failed to update package.json in the template:",
+          e.message
+        );
+      }
+    }
+
+    return { ok: true };
   } catch (err) {
-    console.error("Erro ao copiar o template:", err);
+    return { ok: false, error: err.message || String(err) };
   }
 }
 
-module.exports = { copyTemplate };
+module.exports = { copyTemplate };

package/core/addRoute.js

@@ -1,10 +1,161 @@
-function addRoute(app, path, handlers = {}) {
-  const supportedMethods = ['get', 'post', 'put', 'delete', 'patch'];
+// core/addRoute.js
+// Adds routes to an Express app using a flexible handlers object.
+// Supports:
+// - handlers as a single function (assumed GET)
+// - handlers as an object with HTTP methods (get, post, put, delete, patch, all)
+// - nested subpaths as keys beginning with '/' (e.g. '/:id': { get: fn })
+// - handlers as arrays of functions (middleware chains)
 
-  for (const method of supportedMethods) {
-    if (handlers[method]) {
-      app[method](path, handlers[method]);
+const supportedMethods = ["get", "post", "put", "delete", "patch", "all"];
+
+function isPlainObject(v) {
+  return v && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Normalize a handler entry into an array of functions.
+ * Acceptable inputs: function | [function, function, ...]
+ * @param {Function|Function[]} h
+ * @returns {Function[]}
+ */
+function normalizeHandlersToArray(h) {
+  if (typeof h === "function") return [h];
+  if (Array.isArray(h)) {
+    const invalid = h.find((fn) => typeof fn !== "function");
+    if (invalid) {
+      throw new Error("Each element in handler array must be a function");
+    }
+    return h;
+  }
+  throw new Error("Handler must be a function or an array of functions");
+}
+
+/**
+ * Wrap a handler function to catch thrown errors / rejected promises
+ * and forward them to next(err).
+ * @param {Function} fn
+ * @returns {Function} async wrapper (req, res, next)
+ */
+function wrapHandler(fn) {
+  return async function wrapped(req, res, next) {
+    try {
+      // support handlers that expect next as third argument
+      const maybePromise = fn(req, res, next);
+      // if handler returns a promise, await it to catch rejections
+      if (maybePromise && typeof maybePromise.then === "function") {
+        await maybePromise;
+      }
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+/**
+ * Join basePath and subKey in a safe manner (avoid duplicate slashes).
+ * @param {string} basePath
+ * @param {string} key
+ * @returns {string}
+ */
+function joinPaths(basePath, key) {
+  if (!basePath.endsWith("/")) basePath = basePath;
+  // remove trailing slash from basePath (except if basePath === '/')
+  if (basePath !== "/" && basePath.endsWith("/")) {
+    basePath = basePath.slice(0, -1);
+  }
+  // ensure key starts with '/'
+  const k = key.startsWith("/") ? key : "/" + key;
+  // special case: basePath === '/' -> result is key
+  return basePath === "/" ? k : basePath + k;
+}
+
+/**
+ * Registers routes on the provided Express app.
+ * @param {Object} app - Express app instance
+ * @param {string} basePath - base route path (e.g. '/users')
+ * @param {Function|Object} handlers - single handler function or object map of handlers
+ */
+function addRoute(app, basePath, handlers = {}) {
+  if (!app || typeof app.use !== "function") {
+    throw new Error("Invalid app instance: cannot register routes");
+  }
+
+  if (typeof basePath !== "string") {
+    throw new Error("Invalid path: basePath must be a string");
+  }
+
+  // If handlers is a single function, register it as GET
+  if (typeof handlers === "function" || Array.isArray(handlers)) {
+    const fns = normalizeHandlersToArray(handlers);
+    const wrapped = fns.map(wrapHandler);
+    app.get(basePath, ...wrapped);
+    return;
+  }
+
+  if (!isPlainObject(handlers)) {
+    throw new Error(
+      "Handlers must be a function, an array of functions, or a plain object"
+    );
+  }
+
+  // Iterate keys of handlers
+  for (const key of Object.keys(handlers)) {
+    const value = handlers[key];
+
+    // Nested subpath (key starts with '/')
+    if (key.startsWith("/")) {
+      const subPath = joinPaths(basePath, key);
+
+      // If nested value is a function or array -> assume GET
+      if (typeof value === "function" || Array.isArray(value)) {
+        const fns = normalizeHandlersToArray(value);
+        const wrapped = fns.map(wrapHandler);
+        app.get(subPath, ...wrapped);
+        continue;
+      }
+
+      // If nested value is object -> iterate methods
+      if (isPlainObject(value)) {
+        for (const method of Object.keys(value)) {
+          const handlerFn = value[method];
+          const m = method.toLowerCase();
+          if (!supportedMethods.includes(m)) {
+            throw new Error(
+              `Unsupported HTTP method "${method}" for route "${subPath}"`
+            );
+          }
+          // allow single function or array for handlerFn
+          if (typeof handlerFn !== "function" && !Array.isArray(handlerFn)) {
+            throw new Error(
+              `Handler for ${method} ${subPath} must be a function or array of functions`
+            );
+          }
+          const fns = normalizeHandlersToArray(handlerFn);
+          const wrapped = fns.map(wrapHandler);
+          app[m](subPath, ...wrapped);
+        }
+        continue;
+      }
+
+      throw new Error(`Invalid handler for nested path "${subPath}"`);
+    }
+
+    // Top-level method keys (like 'get', 'post', 'all', etc.)
+    const m = key.toLowerCase();
+    if (!supportedMethods.includes(m)) {
+      throw new Error(
+        `Unsupported key "${key}" in handlers for path "${basePath}"`
+      );
+    }
+    const fn = handlers[key];
+    if (typeof fn !== "function" && !Array.isArray(fn)) {
+      throw new Error(
+        `Handler for ${m.toUpperCase()} ${basePath} must be a function or array of functions`
+      );
     }
+    const fns = normalizeHandlersToArray(fn);
+    const wrapped = fns.map(wrapHandler);
+    app[m](basePath, ...wrapped);
   }
 }
 

package/core/apiRoute.js

@@ -0,0 +1,135 @@
+// core/apiRoute.js
+// Provide a simple helper to create RESTful resource routes.
+// Internally uses addRoute(app, basePath, handlers).
+// Supports:
+// - handlers as a single function (assumed GET on collection)
+// - handlers as an object mapping methods and/or nested subpaths
+// - shorthand CRUD generation: pass { crud: true } or { crud: { list, create, show, update, remove } }
+
+const addRoute = require("./addRoute");
+
+/**
+ * Normalize resource into a base path string.
+ * @param {string} resource
+ * @returns {string} normalized path starting with '/'
+ */
+function normalizeResource(resource) {
+  if (!resource) return "/";
+  if (typeof resource !== "string") {
+    throw new Error("resource must be a string");
+  }
+  let r = resource.trim();
+  if (!r.startsWith("/")) r = "/" + r;
+  if (r.length > 1 && r.endsWith("/")) r = r.slice(0, -1);
+  return r;
+}
+
+/**
+ * Create a stub handler returning 501 Not Implemented.
+ * @param {string} actionName
+ * @returns {Function} express handler
+ */
+function notImplementedHandler(actionName) {
+  return (req, res) => {
+    res
+      .status(501)
+      .json({ error: "Not Implemented", action: actionName || "unknown" });
+  };
+}
+
+/**
+ * Build handlers object for CRUD shorthand.
+ * Accepts optional mapping of handler functions.
+ *
+ * Expected keys supported in `h` (any subset):
+ *  - list / index        -> GET /resource
+ *  - create              -> POST /resource
+ *  - show / get / getById -> GET /resource/:id
+ *  - update              -> PUT /resource/:id
+ *  - remove / delete     -> DELETE /resource/:id
+ *
+ * @param {Object|boolean} h - handlers or true to auto-generate stubs
+ * @returns {Object} handlers object consumable by addRoute
+ */
+function buildCrudHandlers(h) {
+  const provided = h && typeof h === "object" ? h : {};
+  const pick = (keys) => {
+    for (const k of keys) {
+      if (typeof provided[k] === "function") return provided[k];
+    }
+    return null;
+  };
+
+  const listFn = pick(["list", "index"]);
+  const createFn = pick(["create"]);
+  const showFn = pick(["show", "get", "getById"]);
+  const updateFn = pick(["update"]);
+  const removeFn = pick(["remove", "delete"]);
+
+  const handlers = {};
+
+  // collection endpoints
+  handlers.get = listFn || notImplementedHandler("list");
+  handlers.post = createFn || notImplementedHandler("create");
+
+  // member endpoints under '/:id'
+  handlers["/:id"] = {
+    get: showFn || notImplementedHandler("show"),
+    put: updateFn || notImplementedHandler("update"),
+    delete: removeFn || notImplementedHandler("remove"),
+  };
+
+  return handlers;
+}
+
+/**
+ * apiRoute(app, resource, handlers)
+ * @param {Object} app - Express app (Kaelum app)
+ * @param {string} resource - resource name or path (e.g. 'users' or '/users')
+ * @param {Function|Object|boolean} handlers - function, object or shorthand (see README)
+ */
+function apiRoute(app, resource, handlers = {}) {
+  if (!app || typeof app.use !== "function") {
+    throw new Error("Invalid app instance: cannot register apiRoute");
+  }
+
+  const basePath = normalizeResource(resource);
+
+  // If handlers is a function, assume it's a GET on basePath
+  if (typeof handlers === "function") {
+    addRoute(app, basePath, handlers);
+    return;
+  }
+
+  // If handlers is boolean true -> auto CRUD stubs
+  if (handlers === true) {
+    const crudHandlers = buildCrudHandlers(true);
+    addRoute(app, basePath, crudHandlers);
+    return;
+  }
+
+  // If handlers is an object and has a 'crud' key, use it
+  if (
+    handlers &&
+    typeof handlers === "object" &&
+    handlers.hasOwnProperty("crud")
+  ) {
+    const crudSpec = handlers.crud;
+    const crudHandlers = buildCrudHandlers(crudSpec);
+    addRoute(app, basePath, crudHandlers);
+    return;
+  }
+
+  // If handlers is an object, assume it's the direct handlers map for addRoute
+  if (handlers && typeof handlers === "object") {
+    addRoute(app, basePath, handlers);
+    return;
+  }
+
+  // anything else is invalid
+  throw new Error(
+    "Handlers must be a function, an object, or boolean true for CRUD shorthand"
+  );
+}
+
+module.exports = apiRoute;