kaelum 1.1.0 → 1.3.0

package/README.md

@@ -1,134 +1,248 @@
 # Kaelum
 
-**Kaelum** is a minimalist Node.js framework designed to simplify the creation of web pages and REST APIs, especially for beginners and students. Inspired by Python's clean syntax and powered by Express.js, Kaelum automates project setup and server configuration with an intuitive CLI.
+**Kaelum.JS** — Minimalist Node.js framework to simplify creation of web pages and REST APIs.  
+Designed for students and developers who want a fast, opinionated project scaffold and a small, friendly API that encapsulates common Express.js boilerplate.
 
-## 📦 Installation
+---
+
+## 🚀 Quick start
 
-You can create a new project with Kaelum using:
+Create a new project (interactive):
 
 ```bash
 npx kaelum create
 ````
 
-This command initializes a Kaelum project with a pre-configured structure based on the MVC model, including:
+Or create non-interactively (project name + template):
 
-* Static file serving
-* Template-ready HTML/CSS homepage
-* Built-in route system
-* Public folder and initial structure
+```bash
+npx kaelum create my-app --template web
+# or
+npx kaelum create my-api --template api
+```
 
-Then install dependencies and start your app:
+Then:
 
 ```bash
-cd my-project
+cd my-app
 npm install
 npm start
 ```
 
-> **Note:** No need to install Kaelum globally. `npx` handles it automatically!
+> No need to install Kaelum globally — `npx` handles execution.
 
 ---
 
-## 🧠 Why Kaelum?
+## 📦 What Kaelum provides
 
-* 📂 Minimalist MVC folder structure
-* ⚙️ Auto-configured Express setup
-* 🔒 Built-in support for CORS and Helmet
-* 🧱 Easy route management
-* 🧪 Great for learning and building quick prototypes
+* CLI that scaffolds a ready-to-run project (Web or API template) using an opinionated **MVC** structure.
+* Thin abstraction layer over **Express.js** that:
+
+  * automates JSON / URL-encoded parsing by default,
+  * automatically configures common security middlewares via `setConfig` (CORS, Helmet),
+  * exposes a small, easy-to-learn API for routes, middleware and configuration.
+* Small set of helpers for common tasks: `start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`, and more.
+
+Kaelum aims to reduce the initial setup burden while keeping flexibility for advanced users.
 
 ---
 
-## 📁 Web Template Structure
+## 📁 Template structures
 
-After running `npx kaelum create`, the web template structure looks like this:
+### Web template (created by `npx kaelum create <name>` with template `web`)
 
 ```
 my-web-app/
-├── public/          # Static files (e.g., CSS, JS)
+├── public/          # Static files (CSS, JS)
 │   └── style.css
 ├── views/           # HTML templates
 │   └── index.html
-├── controllers/     # Page controller logic
+├── controllers/     # Controller logic (MVC)
 │   └── .gitkeep
 ├── middlewares/     # Custom middlewares
-│   └── example.js
-├── routes.js        # Route definitions
-├── app.js           # Server initialization
-└── package.json     # Project metadata and dependencies
+│   └── logger.js
+├── routes.js        # Route definitions (example uses Kaelum helpers)
+├── app.js           # Server initialization (uses Kaelum API)
+└── package.json
+```
+
+### API template (`--template api`)
+
+```
+my-api-app/
+├── controllers/
+│   └── usersController.js
+├── middlewares/
+│   └── authMock.js
+├── routes.js
+├── app.js
+└── package.json
 ```
 
 ---
 
-## 🚀 Features
+## 🧩 Core API (examples — CommonJS)
 
-Kaelum exposes simple utilities that make it easy to build a web server:
+> Kaelum exposes a factory — use `require('kaelum')` and call it to get an app instance:
 
 ```js
 const kaelum = require('kaelum');
 const app = kaelum();
 ```
 
-### 🌐 `addRoute(path, handlers)`
+### `app.setConfig(options)`
 
-Add routes with GET, POST, PUT, DELETE handlers in one place.
+Enable/disable common features:
 
 ```js
-addRoute('/home', {
-  get: (req, res) => res.send('GET: Welcome!'),
-  post: (req, res) => res.send('POST: Data received!')
+app.setConfig({
+  cors: true,         // apply CORS (requires cors package in dependencies)
+  helmet: true,       // apply Helmet
+  static: "public",   // serve static files from "public"
+  bodyParser: true,   // default: enabled (JSON + urlencoded)
+  logs: false,        // enable request logging via morgan (if installed)
+  port: 3000          // prefered port (used when calling app.start() without port)
 });
 ```
 
-### 🔐 `setMiddleware(middleware)`
+* `setConfig` persists settings to the Kaelum config and will install/remove Kaelum-managed middlewares.
+* Kaelum enables JSON/urlencoded parsing by default so beginners won't forget to parse request bodies.
+
+---
+
+### `app.start(port, callback)`
 
-Globally apply middleware to all routes.
+Starts the HTTP server. If `port` is omitted, Kaelum reads `port` from `setConfig` or falls back to `3000`.
 
 ```js
-setMiddleware(require('helmet')());
+app.start(3000, () => console.log('Running'));
 ```
 
-### ⚙️ `setConfig(options)`
+---
+
+### `app.addRoute(path, handlers)` and `app.apiRoute(resource, handlers)`
 
-You can enable common configurations using `setConfig`:
+Register routes easily:
 
 ```js
-app.setConfig({
-  cors: true,
-  helmet: true,
+app.addRoute('/home', {
+  get: (req, res) => res.send('Welcome!'),
+  post: (req, res) => res.send('Posted!')
+});
+
+// apiRoute builds RESTy resources with nested subpaths:
+app.apiRoute('users', {
+  get: listUsers,
+  post: createUser,
+  '/:id': {
+    get: getUserById,
+    put: updateUser,
+    delete: deleteUser
+  }
 });
 ```
 
-Internally, Kaelum will automatically load and apply `cors` and `helmet` if enabled.
+`addRoute` also accepts a single handler function (assumed `GET`).
+
+---
+
+### `app.setMiddleware(...)`
+
+Flexible helper to register middleware(s):
+
+```js
+// single middleware
+app.setMiddleware(require('helmet')());
+
+// array of middlewares
+app.setMiddleware([mw1, mw2]);
+
+// mount middleware on a path
+app.setMiddleware('/admin', authMiddleware);
+```
+
+---
 
-### 🚀 `start(port)`
+### `app.redirect(from, to, status)`
 
-Start the server.
+Register a redirect route:
 
 ```js
-start(3000);
+app.redirect('/old-url', '/new-url', 302);
 ```
 
 ---
 
-## 👨‍💻 Local Development (for contributors)
+### `app.healthCheck(path = '/health')`
 
-If you want to test or improve Kaelum locally:
+Adds a health endpoint returning `{ status: 'OK', uptime, timestamp, pid }`.
+
+---
+
+### `app.useErrorHandler(options)`
+
+Attach Kaelum's default JSON error handler:
+
+```js
+app.useErrorHandler({ exposeStack: false });
+```
+
+It will return standardized JSON for errors and log server-side errors (5xx) to `console.error`.
+
+---
+
+## 🔧 Local development & contributing
+
+To develop Kaelum locally and test the CLI:
 
 ```bash
-git clone https://github.com/MatheusCampagnolo/kaelum.git
+# clone
+git clone https://github.com/<your-repo>/kaelum.git
 cd kaelum
+
+# install & link locally
+npm install
 npm link
+
+# from any folder you can now run the CLI
+npx kaelum create my-test --template web
+# or
+kaelum create my-test    # if linked globally
 ```
 
-Now you can run the CLI from anywhere:
+---
 
-```bash
-npx kaelum create
-```
+
+## 📝 Why Kaelum?
+
+* Reduces repetitive boilerplate required to start Node/Express web projects.
+* Opinionated scaffolding (MVC) helps beginners adopt better structure.
+* Keeps a small API surface: easy to teach and document.
+* Extensible — `setConfig` and middleware helpers allow adding features without exposing Express internals.
+
+---
+
+## ✅ Current status
+
+> Kaelum is under active development. The CLI scaffolds web and API templates and the framework already includes the MVP helpers (`start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`) and security toggles for `cors` and `helmet`.
+
+---
+
+## 📚 Links
+
+* GitHub: `https://github.com/MatheusCampagnolo/kaelum`
+* npm: `https://www.npmjs.com/package/kaelum`
+
+---
+
+## 🧾 License
+
+MIT — see [LICENSE](LICENSE).
 
 ---
 
-## 📄 License
+## ✍️ Notes for maintainers
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+* Templates include `package.json` configured as `commonjs` for now (uses `require`/`module.exports`).
+* Update template `package.json` dependencies to reference Kaelum version when releasing new npm versions.
+* We plan to add full JSDoc for the public API, unit tests (Jest + Supertest) and a docs site in future iterations.

package/cli/create.js

@@ -6,47 +6,80 @@ const { copyTemplate } = require("./utils");
 
 const templatesDir = path.resolve(__dirname, "templates");
 
-async function createProject() {
+/**
+ * createProject - create project from template
+ * @param {Object} defaults - optional { projectName, template }
+ */
+async function createProject(defaults = {}) {
   console.log("🚀 Bem-vindo ao Kaelum CLI!");
 
-  const answers = await inq.prompt([
-    {
-      type: "input",
-      name: "projectName",
-      message: "Qual será o nome do seu projeto?",
-      validate: (input) => (input ? true : "O nome não pode ser vazio."),
-    },
-    {
-      type: "list",
-      name: "template",
-      message: "Qual template você deseja usar?",
-      choices: ["web", "api"],
-    },
-  ]);
-
-  const { projectName, template } = answers;
-  const targetDir = path.resolve(process.cwd(), projectName);
-  const templateDir = path.join(templatesDir, template);
-
-  if (template === "api") {
-    console.log(
-      '\n📦 O template API ainda está em desenvolvimento. Por favor, escolha o template "web".'
-    );
-    return;
-  }
+  try {
+    // ensure templates dir exists
+    const templatesExists = await fs.pathExists(templatesDir);
+    if (!templatesExists) {
+      console.error("❌ Diretório de templates não encontrado no CLI.");
+      return;
+    }
 
-  if (fs.existsSync(targetDir)) {
-    console.error(
-      `\n❌ A pasta "${projectName}" já existe. Escolha outro nome ou apague a pasta existente.`
-    );
-    return;
-  }
+    // gather answers (use defaults when present)
+    const answers = await inq.prompt([
+      {
+        type: "input",
+        name: "projectName",
+        message: "Qual será o nome do seu projeto?",
+        default: defaults.projectName || "",
+        validate: (input) => (input ? true : "O nome não pode ser vazio."),
+      },
+      {
+        type: "list",
+        name: "template",
+        message: "Qual template você deseja usar?",
+        choices: async () => {
+          // list available template folders
+          try {
+            const items = await fs.readdir(templatesDir, {
+              withFileTypes: true,
+            });
+            return items.filter((i) => i.isDirectory()).map((i) => i.name);
+          } catch (e) {
+            return ["web", "api"];
+          }
+        },
+        default: defaults.template || "web",
+      },
+    ]);
+
+    const { projectName, template } = answers;
+    const targetDir = path.resolve(process.cwd(), projectName);
+    const templateDir = path.join(templatesDir, template);
 
-  await copyTemplate(templateDir, targetDir);
+    // template existence check
+    const templateExists = await fs.pathExists(templateDir);
+    if (!templateExists) {
+      console.error(`\n❌ Template "${template}" não encontrado.`);
+      return;
+    }
 
-  console.log(`\n✅ Projeto "${projectName}" criado com sucesso!`);
-  console.log(`➡️  Acesse a pasta: cd ${projectName}`);
-  console.log(`➡️  Inicie o projeto com: npm install && npm start\n`);
+    if (await fs.pathExists(targetDir)) {
+      console.error(
+        `\n❌ A pasta "${projectName}" já existe. Escolha outro nome ou apague a pasta existente.`
+      );
+      return;
+    }
+
+    // copy + update package.json
+    const result = await copyTemplate(templateDir, targetDir, projectName);
+    if (!result.ok) {
+      console.error(`\n❌ Erro ao copiar o template: ${result.error}`);
+      return;
+    }
+
+    console.log(`\n✅ Projeto "${projectName}" criado com sucesso!`);
+    console.log(`➡️  Acesse a pasta: cd ${projectName}`);
+    console.log(`➡️  Inicie o projeto com: npm install && npm start\n`);
+  } catch (err) {
+    console.error("❌ Erro inesperado:", err.message || err);
+  }
 }
 
-module.exports = { createProject };
+module.exports = { createProject };

package/cli/index.js

@@ -1,11 +1,53 @@
-#!/usr/bin/env node
-const { createProject } = require('./create');
+#!/usr/bin/env node
+const { createProject } = require("./create");
+const argv = process.argv.slice(2);
 
-const [,, command] = process.argv;
+function printHelp() {
+  console.log(`Kaelum CLI
+Usage:
+  kaelum create             # interactive
+  kaelum create <name>      # create using interactive template choice
+  kaelum create <name> --template web|api   # non-interactive (name provided, template preselected)
+  kaelum help
+`);
+}
+
+async function main() {
+  const [command, maybeName, maybeFlag, maybeTemplate] = argv;
+
+  if (
+    !command ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    printHelp();
+    return;
+  }
+
+  if (command === "create") {
+    // non-interactive shorthand: kaelum create my-app --template web
+    if (maybeName && maybeFlag === "--template" && maybeTemplate) {
+      await createProject({ projectName: maybeName, template: maybeTemplate });
+      return;
+    }
+
+    // non-interactive shorthand: kaelum create my-app  (will still ask template)
+    if (maybeName && !maybeFlag) {
+      await createProject({ projectName: maybeName });
+      return;
+    }
+
+    // otherwise interactive flow
+    await createProject();
+    return;
+  }
 
-if (command === 'create') {
-  createProject();
-} else {
   console.log(`Comando não reconhecido: ${command}`);
-  console.log(`Use: kaelum create`);
+  printHelp();
 }
+
+main().catch((err) => {
+  console.error("Error running Kaelum CLI:", err);
+  process.exit(1);
+});

package/cli/templates/api/app.js

@@ -0,0 +1,26 @@
+// app.js - example API project generated by Kaelum (API template)
+const kaelum = require("kaelum");
+
+const app = kaelum();
+
+// enable basic safety + logs via setConfig
+app.setConfig({
+  cors: true,
+  helmet: true,
+  logs: true, // uses morgan internally
+  bodyParser: true,
+});
+
+// mount routes
+const routes = require("./routes");
+routes(app);
+
+// health check
+app.healthCheck("/health");
+
+// use Kaelum generic error handler (JSON responses)
+app.useErrorHandler({ exposeStack: false });
+
+// start server
+const PORT = process.env.PORT || 4000;
+app.start(PORT);

package/cli/templates/api/controllers/usersController.js

@@ -0,0 +1,58 @@
+// controllers/usersController.js
+// Simple in-memory users controller for demonstration.
+
+let _id = 1;
+const users = [
+  { id: _id++, name: "Alice", email: "alice@example.com" },
+  { id: _id++, name: "Bob", email: "bob@example.com" },
+];
+
+function getUsers(req, res) {
+  res.json({ data: users });
+}
+
+function createUser(req, res) {
+  const body = req.body || {};
+  if (!body.name || !body.email) {
+    return res
+      .status(400)
+      .json({ error: { message: "name and email required" } });
+  }
+  const user = { id: _id++, name: body.name, email: body.email };
+  users.push(user);
+  res.status(201).json({ data: user });
+}
+
+function getUserById(req, res) {
+  const id = Number(req.params.id);
+  const u = users.find((x) => x.id === id);
+  if (!u) return res.status(404).json({ error: { message: "User not found" } });
+  res.json({ data: u });
+}
+
+function updateUser(req, res) {
+  const id = Number(req.params.id);
+  const u = users.find((x) => x.id === id);
+  if (!u) return res.status(404).json({ error: { message: "User not found" } });
+  const body = req.body || {};
+  if (body.name) u.name = body.name;
+  if (body.email) u.email = body.email;
+  res.json({ data: u });
+}
+
+function deleteUser(req, res) {
+  const id = Number(req.params.id);
+  const idx = users.findIndex((x) => x.id === id);
+  if (idx === -1)
+    return res.status(404).json({ error: { message: "User not found" } });
+  const removed = users.splice(idx, 1)[0];
+  res.json({ data: removed });
+}
+
+module.exports = {
+  getUsers,
+  createUser,
+  getUserById,
+  updateUser,
+  deleteUser,
+};

package/cli/templates/api/middlewares/authMock.js

@@ -0,0 +1,13 @@
+// middlewares/authMock.js
+// Simple mock "authentication" middleware for demo purposes.
+// Checks for header "x-api-key: secret" — if absent, returns 401.
+
+module.exports = function (req, res, next) {
+  const key = req.headers["x-api-key"] || req.query.api_key;
+  if (!key || key !== "secret") {
+    return res
+      .status(401)
+      .json({ error: { message: "Unauthorized. Provide x-api-key: secret" } });
+  }
+  next();
+};

package/cli/templates/api/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "kaelum-api-app",
+  "version": "0.1.0",
+  "description": "Exemplo de app API gerado pela CLI Kaelum",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "kaelum",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "kaelum": "^1.3.0",
+    "cors": "^2.8.5",
+    "helmet": "^6.0.0",
+    "morgan": "^1.10.0"
+  },
+  "devDependencies": {
+    "nodemon": "^2.0.22"
+  }
+}

package/cli/templates/api/routes.js

@@ -0,0 +1,34 @@
+// routes.js - registers API endpoints using app.apiRoute
+const {
+  getUsers,
+  createUser,
+  getUserById,
+  updateUser,
+  deleteUser,
+} = require("./controllers/usersController");
+
+const auth = require("./middlewares/authMock");
+
+module.exports = function (app) {
+  // Global example: apply auth middleware on /users POST (create)
+  // also demonstrate per-path middleware usage via setMiddleware(path, middleware)
+  app.setMiddleware("/users", (req, res, next) => {
+    // a small wrapper to demonstrate both setMiddleware signature and route-level control
+    // allow GET without auth, require auth for POST/PUT/DELETE by checking method
+    if (["POST", "PUT", "DELETE"].includes(req.method)) {
+      return require("./middlewares/authMock")(req, res, next);
+    }
+    next();
+  });
+
+  // Resource routes using apiRoute
+  app.apiRoute("users", {
+    get: getUsers,
+    post: createUser,
+    "/:id": {
+      get: getUserById,
+      put: updateUser,
+      delete: deleteUser,
+    },
+  });
+};

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);