kaelum 1.3.2 → 1.3.4

package/README.md

@@ -1,9 +1,22 @@
-# Kaelum
+<div align="center">
 
-**Kaelum.JS** — Minimalist Node.js framework to simplify creation of web pages and REST APIs.  
+<h1>Kaelum</h1>
+
+[![npm version](https://img.shields.io/npm/v/kaelum)](https://www.npmjs.com/package/kaelum)
+[![Build Status](https://github.com/MatheusCampagnolo/kaelum/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/MatheusCampagnolo/kaelum/actions)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://matheuscampagnolo.github.io/kaelum/)
+
+**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.
 
----
+👉 [**Read the full documentation here**](https://matheuscampagnolo.github.io/kaelum/)
+
+**If Kaelum helps you, consider supporting its development:**
+
+<a href='https://ko-fi.com/Z8Z51NK4KT' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+
+</div>
 
 ## 🚀 Quick start
 
@@ -11,7 +24,7 @@ Create a new project (interactive):
 
 ```bash
 npx kaelum create
-````
+```
 
 Or create non-interactively (project name + template):
 
@@ -35,13 +48,14 @@ npm start
 
 ## 📦 What Kaelum provides
 
-* CLI that scaffolds a ready-to-run project (Web or API template) using an opinionated **MVC** structure.
-* Thin abstraction layer over **Express.js** that:
+- 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.
 
-  * 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.
+- 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.
 
@@ -49,7 +63,7 @@ Kaelum aims to reduce the initial setup burden while keeping flexibility for adv
 
 ## 📁 Template structures
 
-### Web template (created by `npx kaelum create <name>` with template `web`)
+### Web template (`--template web`)
 
 ```
 my-web-app/
@@ -81,12 +95,12 @@ my-api-app/
 
 ---
 
-## 🧩 Core API (examples — CommonJS)
+## 🧩 Core API
 
 > Kaelum exposes a factory — use `require('kaelum')` and call it to get an app instance:
 
 ```js
-const kaelum = require('kaelum');
+const kaelum = require("kaelum");
 const app = kaelum();
 ```
 
@@ -96,17 +110,17 @@ Enable/disable common features:
 
 ```js
 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)
+  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)
 });
 ```
 
-* `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.
+- `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.
 
 ---
 
@@ -115,7 +129,7 @@ app.setConfig({
 Starts the HTTP server. If `port` is omitted, Kaelum reads `port` from `setConfig` or falls back to `3000`.
 
 ```js
-app.start(3000, () => console.log('Running'));
+app.start(3000, () => console.log("Running"));
 ```
 
 ---
@@ -125,20 +139,20 @@ app.start(3000, () => console.log('Running'));
 Register routes easily:
 
 ```js
-app.addRoute('/home', {
-  get: (req, res) => res.send('Welcome!'),
-  post: (req, res) => res.send('Posted!')
+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', {
+app.apiRoute("users", {
   get: listUsers,
   post: createUser,
-  '/:id': {
+  "/:id": {
     get: getUserById,
     put: updateUser,
-    delete: deleteUser
-  }
+    delete: deleteUser,
+  },
 });
 ```
 
@@ -152,13 +166,13 @@ Flexible helper to register middleware(s):
 
 ```js
 // single middleware
-app.setMiddleware(require('helmet')());
+app.setMiddleware(require("helmet")());
 
 // array of middlewares
 app.setMiddleware([mw1, mw2]);
 
 // mount middleware on a path
-app.setMiddleware('/admin', authMiddleware);
+app.setMiddleware("/admin", authMiddleware);
 ```
 
 ---
@@ -168,7 +182,7 @@ app.setMiddleware('/admin', authMiddleware);
 Register a redirect route:
 
 ```js
-app.redirect('/old-url', '/new-url', 302);
+app.redirect("/old-url", "/new-url", 302);
 ```
 
 ---
@@ -193,45 +207,42 @@ It will return standardized JSON for errors and log server-side errors (5xx) to
 
 ## 🔧 Local development & contributing
 
-To develop Kaelum locally and test the CLI:
-
 ```bash
-# clone
 git clone https://github.com/MatheusCampagnolo/kaelum.git
 cd kaelum
-
-# install & link locally
 npm install
 npm link
+```
+
+Now you can test the CLI locally:
 
-# from any folder you can now run the CLI
+```bash
 npx kaelum create my-test --template web
-# or
-kaelum create my-test    # if linked globally
 ```
 
 ---
 
-
 ## 📝 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.
+- 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`.
+> Kaelum is under active development.
+> CLI scaffolds web and API templates, and the framework 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`
+- [GitHub](https://github.com/MatheusCampagnolo/kaelum)
+- [npm](https://www.npmjs.com/package/kaelum)
+- [Documentation](https://matheuscampagnolo.github.io/kaelum/)
 
 ---
 
@@ -243,6 +254,5 @@ MIT — see [LICENSE](LICENSE).
 
 ## ✍️ Notes for maintainers
 
-* 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.
+- Templates use `commonjs` (`require` / `module.exports`).
+- Update template dependencies to reference the correct Kaelum version when releasing new npm versions.

package/cli/create.js

@@ -3,12 +3,42 @@ const inq = inquirer.default || inquirer;
 const path = require("path");
 const fs = require("fs-extra");
 const { copyTemplate } = require("./utils");
+const { spawn } = require("child_process");
 
 const templatesDir = path.resolve(__dirname, "templates");
 
+/**
+ * runInstall - runs `npm ci` if package-lock exists, otherwise `npm install`
+ * @param {string} cwd - target directory where install runs
+ * @returns {Promise<void>}
+ */
+function runInstall(cwd) {
+  return new Promise((resolve, reject) => {
+    const lockExists = fs.existsSync(path.join(cwd, "package-lock.json"));
+    const cmd = "npm";
+    const args = lockExists ? ["ci"] : ["install"];
+
+    // Spawn child process and inherit stdio so user sees progress
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32", // improves compatibility on Windows
+    });
+
+    child.on("error", (err) => {
+      reject(err);
+    });
+
+    child.on("exit", (code) => {
+      if (code === 0) return resolve();
+      reject(new Error(`${cmd} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+
 /**
  * createProject - create project from template
- * @param {Object} defaults - optional { projectName, template }
+ * @param {Object} defaults - optional { projectName, template, autoInstall }
  */
 async function createProject(defaults = {}) {
   console.log("🚀 Bem-vindo ao Kaelum CLI!");
@@ -47,9 +77,19 @@ async function createProject(defaults = {}) {
         },
         default: defaults.template || "web",
       },
+      {
+        type: "confirm",
+        name: "autoInstall",
+        message:
+          "Deseja que eu execute 'npm install' agora (recomendado)?",
+        default:
+          typeof defaults.autoInstall === "boolean"
+            ? defaults.autoInstall
+            : true,
+      },
     ]);
 
-    const { projectName, template } = answers;
+    const { projectName, template, autoInstall } = answers;
     const targetDir = path.resolve(process.cwd(), projectName);
     const templateDir = path.join(templatesDir, template);
 
@@ -76,10 +116,26 @@ async function createProject(defaults = {}) {
 
     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 (autoInstall) {
+      console.log("⬇️  Instalando dependências (npm)... (isso pode levar alguns minutos)");
+      try {
+        await runInstall(targetDir);
+        console.log("\n✅ Dependências instaladas com sucesso!");
+        console.log("➡️  Para iniciar o projeto, execute: npm start\n");
+      } catch (installErr) {
+        console.error(
+          "\n❌ Falha ao instalar dependências automaticamente:",
+          installErr.message || installErr
+        );
+        console.log(`➡️  Tente manualmente: cd ${projectName} && npm install`);
+      }
+    } else {
+      console.log(`➡️  Inicie o projeto com: cd ${projectName} && 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,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 const { createProject } = require("./create");
 const argv = process.argv.slice(2);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaelum",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A minimalist Node.js framework for building web pages and APIs with simplicity and speed.",
   "main": "index.js",
   "exports": {