create-kaelum 0.0.0-stage → 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matheus Messias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# create-kaelum
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a new [Kaelum](https://github.com/kaelumjs/kaelum) project.
+
+```bash
+npm create kaelum@latest
+```
+
+Pass a name and a template to skip the questions:
+
+```bash
+npm create kaelum@latest my-api -- --template ts-api
+```
+
+## Templates
+
+| Template | Description                                    |
+| :------- | :--------------------------------------------- |
+| `js-web` | JavaScript, MVC with views and static files    |
+| `js-api` | JavaScript, REST API                           |
+| `ts-web` | TypeScript, MVC with views and static files    |
+| `ts-api` | TypeScript, REST API                           |
+
+## Options
+
+| Option                  | Description                                   |
+| :---------------------- | :-------------------------------------------- |
+| `-t, --template <name>` | Template to use                               |
+| `--install`             | Install dependencies without asking           |
+| `--no-install`          | Skip installing dependencies without asking   |
+| `-h, --help`            | Show help                                     |
+| `-v, --version`         | Show the installed version                    |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "create-kaelum",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.0",
+  "description": "Scaffold a new Kaelum project.",
+  "type": "commonjs",
+  "bin": {
+    "create-kaelum": "src/index.js"
+  },
+  "files": [
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\""
+  },
+  "keywords": [
+    "kaelum",
+    "create",
+    "scaffold",
+    "cli",
+    "starter",
+    "express"
+  ],
+  "author": "Matheus Campagnolo",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.22.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaelumjs/kaelum.git",
+    "directory": "packages/create-kaelum"
+  },
+  "bugs": {
+    "url": "https://github.com/kaelumjs/kaelum/issues"
+  },
+  "homepage": "https://kaelumjs.matthcodes.dev",
+  "dependencies": {
+    "inquirer": "12.11.1"
+  }
+}

package/src/create.js

@@ -0,0 +1,184 @@
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { copyTemplate, pathExists } = require("./utils");
+const { version } = require("../package.json");
+
+// kaelum and create-kaelum are released together with the same version, so a
+// project scaffolded by this CLI depends on the matching kaelum release.
+const kaelumVersion = `^${version}`;
+
+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>}
+ */
+async function runInstall(cwd) {
+  const lockExists = await pathExists(path.join(cwd, "package-lock.json"));
+  const cmd = "npm";
+  const args = lockExists ? ["ci"] : ["install"];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) return resolve();
+      reject(new Error(`${cmd} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+
+/**
+ * Ask only for what was not provided up front. Returns an empty object, and
+ * never loads the prompt library, when there is nothing to ask.
+ * @param {Object} defaults
+ */
+async function askMissing(defaults) {
+  const questions = [];
+
+  if (!defaults.projectName) {
+    questions.push({
+      type: "input",
+      name: "projectName",
+      message: "What is your project name?",
+      validate: (input) => (input ? true : "Project name cannot be empty."),
+    });
+  }
+
+  if (!defaults.language) {
+    questions.push({
+      type: "list",
+      name: "language",
+      message: "Choose your language:",
+      choices: [
+        { name: "JavaScript", value: "js" },
+        { name: "TypeScript", value: "ts" },
+      ],
+      default: "js",
+    });
+  }
+
+  if (!defaults.template) {
+    questions.push({
+      type: "list",
+      name: "template",
+      message: "Choose your template:",
+      choices: [
+        { name: "web — MVC with views & static files", value: "web" },
+        { name: "api — REST API ready", value: "api" },
+      ],
+      default: "web",
+    });
+  }
+
+  if (typeof defaults.autoInstall !== "boolean") {
+    questions.push({
+      type: "confirm",
+      name: "autoInstall",
+      message: "Install dependencies now? (recommended)",
+      default: true,
+    });
+  }
+
+  if (questions.length === 0) return {};
+
+  const inquirer = require("inquirer");
+  return (inquirer.default || inquirer).prompt(questions);
+}
+
+/**
+ * createProject - create project from template
+ * @param {Object} defaults - optional { projectName, language, template, autoInstall }
+ * @returns {Promise<boolean>} true when the project was created
+ */
+async function createProject(defaults = {}) {
+  console.log("🚀 Welcome to Kaelum!\n");
+
+  try {
+    const answers = await askMissing(defaults);
+
+    const projectName = defaults.projectName || answers.projectName;
+    const language = defaults.language || answers.language;
+    const template = defaults.template || answers.template;
+    const autoInstall =
+      typeof defaults.autoInstall === "boolean" ? defaults.autoInstall : answers.autoInstall;
+
+    const targetDir = path.resolve(process.cwd(), projectName);
+    const templateDir = path.join(templatesDir, language, template);
+
+    if (!(await pathExists(templateDir))) {
+      console.error(`\n❌ Template "${language}/${template}" not found.`);
+      return false;
+    }
+
+    if (await pathExists(targetDir)) {
+      console.error(
+        `\n❌ Folder "${projectName}" already exists. Choose a different name or delete the existing folder.`
+      );
+      return false;
+    }
+
+    // Copy template, update package.json, generate .env and .gitignore
+    const isTypeScript = language === "ts";
+    const result = await copyTemplate(
+      templateDir,
+      targetDir,
+      path.basename(targetDir),
+      kaelumVersion
+    );
+    if (!result.ok) {
+      console.error(`\n❌ Error copying template: ${result.error}`);
+      return false;
+    }
+
+    // Post-creation summary
+    const langLabel = isTypeScript ? "TypeScript" : "JavaScript";
+    console.log(`\n✅ Project "${projectName}" created successfully!`);
+    console.log(`   Language: ${langLabel}`);
+    console.log(`   Template: ${template}`);
+    console.log(`\n📁 cd ${projectName}`);
+
+    if (autoInstall) {
+      console.log("📦 Installing dependencies... (this may take a few minutes)\n");
+      try {
+        await runInstall(targetDir);
+        console.log("\n✅ Dependencies installed successfully!");
+        printNextSteps({ isTypeScript });
+      } catch (installErr) {
+        console.error(
+          "\n❌ Failed to install dependencies automatically:",
+          installErr.message || installErr
+        );
+        console.log(`➡️  Try manually: cd ${projectName} && npm install`);
+      }
+    } else {
+      printNextSteps({ isTypeScript, install: `cd ${projectName} && npm install` });
+    }
+
+    return true;
+  } catch (err) {
+    console.error("❌ Unexpected error:", err.message || err);
+    return false;
+  }
+}
+
+function printNextSteps({ isTypeScript, install }) {
+  console.log("\n📌 Next steps:");
+  if (install) console.log(`   ${install}`);
+  if (isTypeScript) {
+    console.log(`   npm run dev     Start development server (tsx watch)`);
+    console.log(`   npm run build   Compile TypeScript to JavaScript`);
+    console.log(`   npm start       Run compiled output\n`);
+  } else {
+    console.log(`   npm start       Start the server`);
+    console.log(`   npm run dev     Start with file watching\n`);
+  }
+}
+
+module.exports = { createProject };

package/src/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+const { parseArgs } = require("node:util");
+const { createProject } = require("./create");
+const { version } = require("../package.json");
+
+const TEMPLATES = {
+  "js-web": { language: "js", template: "web" },
+  "js-api": { language: "js", template: "api" },
+  "ts-web": { language: "ts", template: "web" },
+  "ts-api": { language: "ts", template: "api" },
+};
+
+// Kept for backward compatibility with `kaelum create --template web|api`.
+const TEMPLATE_ALIASES = { web: "js-web", api: "js-api" };
+
+function printHelp() {
+  console.log(`
+create-kaelum v${version}
+
+Usage:
+  npm create kaelum@latest                              Interactive mode
+  npm create kaelum@latest <name>                       Ask for language and template
+  npm create kaelum@latest <name> -- --template <t>     Skip the template questions
+
+Options:
+  -t, --template <template>   js-web, js-api, ts-web or ts-api (aliases: web, api)
+      --install               Install dependencies without asking
+      --no-install            Skip installing dependencies without asking
+  -h, --help                  Show this help message
+  -v, --version               Show the installed version
+
+Templates:
+  js-web     JavaScript + MVC with views & static files
+  js-api     JavaScript + REST API
+  ts-web     TypeScript + MVC with views & static files
+  ts-api     TypeScript + REST API
+
+Examples:
+  npm create kaelum@latest my-app -- --template ts-web
+  npm create kaelum@latest my-api -- --template js-api --no-install
+`);
+}
+
+/**
+ * Parse a template name such as "ts-api" into { language, template }.
+ * Returns null when the name is unknown.
+ */
+function parseTemplate(value) {
+  return TEMPLATES[TEMPLATE_ALIASES[value] || value] || null;
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    allowNegative: true,
+    options: {
+      template: { type: "string", short: "t" },
+      install: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+  });
+
+  if (values.version) {
+    console.log(`create-kaelum v${version}`);
+    return;
+  }
+
+  if (values.help) {
+    printHelp();
+    return;
+  }
+
+  const defaults = { projectName: positionals[0], autoInstall: values.install };
+
+  if (values.template) {
+    const parsed = parseTemplate(values.template);
+    if (!parsed) {
+      console.error(`Unknown template: "${values.template}"`);
+      console.error(
+        `Available templates: ${Object.keys(TEMPLATES).join(", ")} (or aliases: web, api)`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    Object.assign(defaults, parsed);
+  }
+
+  const created = await createProject(defaults);
+  if (!created) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  console.error("Error running create-kaelum:", err.message || err);
+  process.exit(1);
+});

package/src/utils.js

@@ -0,0 +1,89 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const DEFAULT_ENV = `PORT=3000
+NODE_ENV=development
+`;
+
+const DEFAULT_GITIGNORE = `node_modules/
+dist/
+.env
+*.log
+`;
+
+/**
+ * @param {string} target
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy a template directory to target and update package.json with projectName.
+ * Also generates .env and .gitignore files.
+ * @param {string} sourceDir
+ * @param {string} targetDir
+ * @param {string} projectName (optional) - will override package.json name if present
+ * @param {string} kaelumVersion (optional) - range written as the `kaelum` dependency
+ */
+async function copyTemplate(sourceDir, targetDir, projectName, kaelumVersion) {
+  try {
+    if (!sourceDir || !targetDir) {
+      throw new Error("Source and target directories are required.");
+    }
+
+    if (!(await pathExists(sourceDir))) {
+      throw new Error(`Template not found: ${sourceDir}`);
+    }
+
+    await fs.cp(sourceDir, targetDir, {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    });
+
+    // Try update package.json in the copied template
+    const pkgPath = path.join(targetDir, "package.json");
+    if (projectName && (await pathExists(pkgPath))) {
+      try {
+        const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+        // 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 create-kaelum`;
+        // Ensure type commonjs by default for templates that expect require/module.exports
+        if (!pkg.type) pkg.type = "commonjs";
+        // Never trust the range baked into the template: it goes stale.
+        if (kaelumVersion && pkg.dependencies && pkg.dependencies.kaelum) {
+          pkg.dependencies.kaelum = kaelumVersion;
+        }
+        await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+      } catch (e) {
+        // Non-fatal: warn but continue
+        console.warn("Warning: failed to update package.json in the template:", e.message);
+      }
+    }
+
+    const envPath = path.join(targetDir, ".env");
+    if (!(await pathExists(envPath))) {
+      await fs.writeFile(envPath, DEFAULT_ENV, "utf8");
+    }
+
+    const gitignorePath = path.join(targetDir, ".gitignore");
+    if (!(await pathExists(gitignorePath))) {
+      await fs.writeFile(gitignorePath, DEFAULT_GITIGNORE, "utf8");
+    }
+
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+module.exports = { copyTemplate, pathExists };

package/templates/js/api/app.js

@@ -0,0 +1,44 @@
+const kaelum = require("kaelum");
+
+const app = kaelum();
+
+// Configure security and logging
+app.setConfig({
+  cors: true,
+  helmet: true,
+  logs: true,
+  bodyParser: true,
+});
+
+// Observability: X-Request-Id + Server-Timing headers
+app.requestId();
+app.timing();
+
+// Semantic response helpers: res.ok(), res.created(), res.notFound(), ...
+app.useResponseHelpers();
+
+// ETag + conditional requests (304 Not Modified)
+app.useEtag();
+
+// Mount routes
+const routes = require("./routes");
+routes(app);
+
+// Health check endpoint
+app.healthCheck("/health");
+
+// Graceful shutdown hook
+app.onShutdown(() => {
+  console.log("Cleaning up resources...");
+});
+
+// 405 for known paths with the wrong method, then 404 for everything else
+app.useMethodNotAllowed();
+app.notFound();
+
+// Error handler (JSON responses)
+app.useErrorHandler({ exposeStack: false });
+
+// Start server
+const PORT = process.env.PORT || 4000;
+app.start(PORT);

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

@@ -0,0 +1,28 @@
+// controllers/usersController.js
+// Simple in-memory controller for Kaelum API demonstration
+
+const users = [
+  { id: 1, name: "Alice", role: "admin" },
+  { id: 2, name: "Bob", role: "user" },
+];
+
+// Uses res.ok / res.created / res.notFound from app.useResponseHelpers()
+exports.list = (req, res) => res.ok(users);
+
+exports.create = (req, res) => {
+  const newUser = { id: users.length + 1, ...req.body };
+  users.push(newUser);
+  res.created({ success: true, user: newUser });
+};
+
+exports.get = (req, res) => {
+  const user = users.find((u) => u.id === Number(req.params.id));
+  return user ? res.ok(user) : res.notFound("User not found");
+};
+
+exports.posts = (req, res) => {
+  res.ok([
+    { id: 101, title: "Kaelum Rocks", userId: req.params.id },
+    { id: 102, title: "Recursive Routing", userId: req.params.id },
+  ]);
+};

package/templates/js/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/templates/js/api/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "kaelum-api-app",
+  "version": "0.1.0",
+  "description": "REST API application generated by Kaelum CLI (api template)",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "node --watch app.js"
+  },
+  "keywords": [
+    "kaelum",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.22.1"
+  },
+  "dependencies": {
+    "kaelum": "*"
+  },
+  "devDependencies": {}
+}

package/templates/js/api/routes.js

@@ -0,0 +1,43 @@
+// routes.js
+const users = require("./controllers/usersController");
+const auth = require("./middlewares/authMock");
+const { validate } = require("kaelum/validate");
+const { version } = require("./package.json");
+
+// Request body validation for POST /users
+const createUserSchema = validate({
+  body: {
+    name: { type: "string", required: true, min: 2, max: 50 },
+    role: { type: "string" },
+  },
+});
+
+module.exports = (app) => {
+  // Global middleware for /users path
+  app.setMiddleware("/users", (req, res, next) => {
+    // Require auth on POST requests
+    if (req.method === "POST") return auth(req, res, next);
+    next();
+  });
+
+  // RESTful nested routing example
+  app.apiRoute("users", {
+    get: users.list,
+    post: [createUserSchema, users.create],
+
+    // Nested parameter: /users/:id
+    "/:id": {
+      get: users.get,
+
+      // Nested resource: /users/:id/posts
+      "/posts": {
+        get: users.posts,
+      },
+    },
+  });
+
+  // Metadata endpoint
+  app.addRoute("/meta", {
+    get: (req, res) => res.ok({ version, framework: "Kaelum" }),
+  });
+};

package/templates/js/web/app.js

@@ -0,0 +1,43 @@
+const kaelum = require("kaelum");
+
+const app = kaelum();
+
+// Configure security, static files, and body parsing
+app.setConfig({
+  cors: true,
+  helmet: true,
+  static: "public",
+  bodyParser: true,
+});
+
+// Observability: X-Request-Id + Server-Timing headers
+app.requestId();
+app.timing();
+
+// Redirect /about/ -> /about
+app.useTrimTrailingSlash();
+
+// Register routes
+const routes = require("./routes");
+routes(app);
+
+// Health check endpoint
+app.healthCheck("/health");
+
+// Graceful shutdown hook
+app.onShutdown(() => {
+  console.log("Cleaning up resources...");
+});
+
+// 405 for known paths with the wrong method, then a custom HTML 404
+app.useMethodNotAllowed();
+app.notFound((_req, res) => {
+  res.status(404).send("<h1>404</h1><p>Page not found.</p>");
+});
+
+// Error handler (returns JSON on errors)
+app.useErrorHandler({ exposeStack: false });
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.start(PORT);