gazan-init 0.1.0

package/bin/gazan.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+
+const REQUIRED_MAJOR = 18;
+const currentMajor = Number(process.versions.node.split(".")[0]);
+
+if (Number.isNaN(currentMajor) || currentMajor < REQUIRED_MAJOR) {
+  console.error(
+    `GAZAN requires Node.js >= ${REQUIRED_MAJOR}. You're running Node ${process.versions.node}.\n` +
+      `Install a newer Node (e.g. via nvm) and try again.`
+  );
+  process.exit(1);
+}
+
+const { createProgram } = require("../src/cli");
+
+createProgram().parseAsync(process.argv);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "gazan-init",
+  "version": "0.1.0",
+  "description": "Interactive CLI that generates production-ready Node.js backend projects — architecture, database, auth, Redis, BullMQ, Socket.IO, and module aliases, all conditional on what you actually select.",
+  "keywords": [
+    "cli",
+    "generator",
+    "scaffolding",
+    "boilerplate",
+    "backend",
+    "express",
+    "prisma",
+    "mongoose",
+    "mongodb",
+    "postgresql",
+    "typescript",
+    "mvc",
+    "hmvc",
+    "code-generator",
+    "project-generator"
+  ],
+  "license": "MIT",
+  "author": "Korveniq Technologies",
+  "type": "commonjs",
+  "bin": {
+    "gazan": "bin/gazan.js"
+  },
+  "main": "src/generators/index.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/korveniq/Gazan.git"
+  },
+  "homepage": "https://github.com/korveniq/Gazan#readme",
+  "bugs": {
+    "url": "https://github.com/korveniq/Gazan/issues"
+  },
+  "scripts": {
+    "test": "node tests/run.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/cli/commands/init.js

@@ -0,0 +1,126 @@
+"use strict";
+
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const fs = require("fs-extra");
+const p = require("@clack/prompts");
+const chalk = require("chalk");
+const { runPrompts } = require("../../prompts");
+const { normalizeConfig } = require("../../config/normalize");
+const { isDirEmpty } = require("../../utils/fsSafety");
+const { readEntityFile } = require("../../parser/entity/parse");
+const { EntityValidationError } = require("../../parser/entity/errors");
+const { AliasCollisionError } = require("../../config/aliases");
+const { generate } = require("../../generators");
+
+/**
+ * Generates into a scratch directory first, only copying into `targetDir` once generation
+ * succeeds fully — so a bug or filesystem error partway through never leaves the user's real
+ * project directory half-written.
+ */
+function generateAtomically(targetDir, config, entityModel) {
+  const tmpDir = path.join(os.tmpdir(), `gazan-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`);
+  try {
+    const { results, warnings } = generate(tmpDir, config, entityModel);
+    fs.ensureDirSync(targetDir);
+    fs.copySync(tmpDir, targetDir, { overwrite: true });
+    return { results, warnings };
+  } finally {
+    fs.removeSync(tmpDir);
+  }
+}
+
+async function resolveTargetDir(projectName) {
+  let targetDir = path.resolve(process.cwd(), projectName);
+
+  for (;;) {
+    if (isDirEmpty(targetDir)) return targetDir;
+
+    const choice = await p.select({
+      message: `Directory "${path.relative(process.cwd(), targetDir) || targetDir}" is not empty.`,
+      options: [
+        { value: "cancel", label: "Cancel" },
+        { value: "continue", label: "Continue (files may be overwritten)" },
+        { value: "other", label: "Use another directory" },
+      ],
+    });
+
+    if (p.isCancel(choice) || choice === "cancel") {
+      p.cancel("Operation cancelled.");
+      process.exit(1);
+    }
+    if (choice === "continue") return targetDir;
+
+    const otherName = await p.text({
+      message: "Target directory path",
+      placeholder: "./my-app",
+    });
+    if (p.isCancel(otherName)) {
+      p.cancel("Operation cancelled.");
+      process.exit(1);
+    }
+    targetDir = path.resolve(process.cwd(), otherName);
+  }
+}
+
+async function runInit() {
+  const answers = await runPrompts();
+
+  const targetDir = await resolveTargetDir(answers.projectName);
+  answers.targetDir = targetDir;
+
+  const config = normalizeConfig(answers);
+
+  let entityModel = null;
+  if (config.entityFile) {
+    try {
+      entityModel = readEntityFile(config.entityFile, { databaseType: config.database.type });
+    } catch (error) {
+      if (error instanceof EntityValidationError) {
+        p.log.error(error.format());
+      } else {
+        p.log.error(error.message);
+      }
+      process.exit(1);
+    }
+  }
+
+  const spinner = p.spinner();
+  spinner.start("Generating project...");
+
+  try {
+    const { results, warnings } = generateAtomically(targetDir, config, entityModel);
+    spinner.stop("Project generated.");
+    for (const step of results) {
+      p.log.success(step);
+    }
+    for (const warning of warnings) {
+      p.log.warn(warning);
+    }
+  } catch (error) {
+    spinner.stop("Generation failed — target directory left untouched.");
+    if (error instanceof AliasCollisionError) {
+      p.log.error(error.message);
+    } else {
+      p.log.error(error.stack || error.message);
+    }
+    process.exit(1);
+  }
+
+  const relTarget = path.relative(process.cwd(), targetDir) || ".";
+
+  p.outro(
+    [
+      chalk.bold.green("Project initialized successfully."),
+      "",
+      "Next steps:",
+      "",
+      `  cd ${relTarget}`,
+      `  npm install`,
+      `  npm run dev`,
+    ].join("\n")
+  );
+}
+
+module.exports = { runInit };

package/src/cli/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const { Command } = require("commander");
+const { runInit } = require("./commands/init");
+const pkg = require("../../package.json");
+
+function createProgram() {
+  const program = new Command();
+
+  program.name("gazan").description("Interactive backend project initializer.").version(pkg.version);
+
+  program
+    .command("init")
+    .description("Interactively generate a new backend project.")
+    .action(async () => {
+      await runInit();
+    });
+
+  return program;
+}
+
+module.exports = { createProgram };

package/src/config/aliases.js

@@ -0,0 +1,130 @@
+"use strict";
+
+const { pluralize } = require("../utils/strings");
+
+class AliasCollisionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AliasCollisionError";
+  }
+}
+
+// Every alias GAZAN itself can generate — used to guard entity-derived HMVC module aliases from
+// colliding with a shared/infra alias (section 11's reserved list, extended with the ones GAZAN
+// actually produces beyond the spec's minimum example, e.g. @models).
+const RESERVED_ALIAS_NAMES = new Set([
+  "@",
+  "@controllers",
+  "@services",
+  "@routes",
+  "@middlewares",
+  "@utils",
+  "@helpers",
+  "@validators",
+  "@configs",
+  "@db",
+  "@redis",
+  "@socket",
+  "@workers",
+  "@models",
+]);
+
+function join(...segments) {
+  const filtered = segments.filter((s) => s && s !== ".");
+  return filtered.length > 0 ? filtered.join("/") : ".";
+}
+
+/**
+ * The single source of truth for the project's alias set. Consumed by the import resolver,
+ * the tsconfig/jsconfig generators, the CJS/MJS runtime generators, and the README generator —
+ * none of them re-derive this mapping independently.
+ *
+ * Returns { enabled: false } untouched when aliases are off, so every downstream consumer can
+ * just check `.enabled` once and otherwise behave exactly as it did before this feature existed.
+ */
+function buildAliasConfig(config, entityModel) {
+  if (!config.aliases || !config.aliases.enabled) {
+    return { enabled: false, root: "@", aliases: {}, modules: {} };
+  }
+
+  const root = config.useSrc ? "src" : ".";
+  const aliases = { "@": root };
+
+  if (config.architecture === "mvc") {
+    aliases["@controllers"] = join(root, "controllers");
+    aliases["@routes"] = join(root, "routes");
+    aliases["@services"] = join(root, "services");
+    aliases["@validators"] = join(root, "validators");
+  }
+
+  // Shared regardless of architecture — generateProject always creates these.
+  aliases["@middlewares"] = join(root, "middlewares");
+  aliases["@utils"] = join(root, "utils");
+  aliases["@helpers"] = join(root, "helpers");
+  aliases["@configs"] = join(root, "configs");
+
+  if (config.database.type !== "none") {
+    aliases["@db"] = join(root, "configs", "db");
+  }
+  if (config.redis) {
+    aliases["@redis"] = join(root, "configs", "redis");
+  }
+  if (config.socketIO) {
+    aliases["@socket"] = join(root, "socket");
+  }
+  if (config.bullMQ) {
+    aliases["@workers"] = join(root, "workers");
+  }
+  if (config.database.type === "mongodb" && config.database.orm === "mongoose") {
+    aliases["@models"] = join(root, "models");
+  }
+
+  const modules = {};
+  if (config.architecture === "hmvc" && entityModel) {
+    const seenTargets = new Map();
+    for (const model of entityModel.models) {
+      if (model.crud === false) continue;
+
+      // model.camelName is already validated by the entity parser (letters/digits only,
+      // starting with a letter), so pluralize() cannot introduce path-traversal or unsafe
+      // characters — no separate sanitization is needed here.
+      const key = `@${pluralize(model.camelName)}`;
+
+      if (RESERVED_ALIAS_NAMES.has(key)) {
+        throw new AliasCollisionError(
+          `Module alias '${key}' (derived from model '${model.name}') collides with a reserved GAZAN alias. Rename the model, or disable module aliases.`
+        );
+      }
+      if (seenTargets.has(key)) {
+        throw new AliasCollisionError(
+          `Module alias '${key}' is derived from both '${seenTargets.get(key)}' and '${model.name}' — their pluralized names collide. Rename one of the models, or disable module aliases.`
+        );
+      }
+      seenTargets.set(key, model.name);
+
+      modules[key] = join(root, "modules", model.camelName);
+    }
+  }
+
+  return { enabled: true, root: "@", aliases, modules };
+}
+
+/** All alias entries (shared + HMVC module) as a single flat map — key -> target directory. */
+function allAliasEntries(aliasConfig) {
+  return { ...aliasConfig.aliases, ...aliasConfig.modules };
+}
+
+/**
+ * Derives tsconfig/jsconfig `paths` (and their `baseUrl`) from the directory map — the only place
+ * that shape is computed, so tsconfig.json and jsconfig.json can never drift from each other or
+ * from the runtime resolvers.
+ */
+function toTsPaths(aliasConfig) {
+  const paths = {};
+  for (const [key, dir] of Object.entries(allAliasEntries(aliasConfig))) {
+    paths[`${key}/*`] = [`${dir === "." ? "" : dir + "/"}*`];
+  }
+  return { baseUrl: ".", paths };
+}
+
+module.exports = { buildAliasConfig, allAliasEntries, toTsPaths, AliasCollisionError, RESERVED_ALIAS_NAMES };

package/src/config/normalize.js

@@ -0,0 +1,65 @@
+"use strict";
+
+/**
+ * Turns raw prompt answers into the single normalized configuration object
+ * that every generator consumes. Generators must never read prompt answers
+ * directly — only this shape.
+ */
+function normalizeConfig(answers) {
+  const moduleSystem = answers.moduleSystem === "mjs" ? "mjs" : "cjs";
+  const language = answers.language === "ts" ? "ts" : "js";
+  const ext = language === "ts" ? "ts" : "js";
+
+  const database = normalizeDatabase(answers.database);
+  const architecture = answers.architecture === "hmvc" ? "hmvc" : "mvc";
+  const useSrc = Boolean(answers.useSrc);
+  const socketIO = Boolean(answers.socketIO);
+  const bullMQ = Boolean(answers.bullMQ);
+
+  const authentication = normalizeAuth(answers.authentication);
+
+  const rateLimitStrategy = bullMQ ? "redis" : answers.rateLimitStrategy || "memory";
+  const needsRedis = bullMQ || rateLimitStrategy === "redis";
+
+  return {
+    projectName: answers.projectName,
+    targetDir: answers.targetDir,
+    moduleSystem,
+    language,
+    ext,
+    aliases: { enabled: Boolean(answers.aliasesEnabled) },
+    database,
+    architecture,
+    useSrc,
+    socketIO,
+    bullMQ,
+    redis: needsRedis,
+    rateLimitStrategy: needsRedis ? "redis" : "memory",
+    authentication,
+    entityFile: answers.entityFile || null,
+  };
+}
+
+function normalizeDatabase(db) {
+  if (!db || db.type === "none") {
+    return { type: "none", orm: null };
+  }
+  if (db.type === "postgresql") {
+    return { type: "postgresql", orm: "prisma" };
+  }
+  if (db.type === "mongodb") {
+    return { type: "mongodb", orm: db.orm === "native" ? "native" : "mongoose" };
+  }
+  return { type: "none", orm: null };
+}
+
+function normalizeAuth(auth) {
+  if (!auth || !auth.enabled) {
+    return { enabled: false, methods: [] };
+  }
+  const allowed = ["email-password", "jwt", "oauth", "refresh-token"];
+  const methods = (auth.methods || []).filter((m) => allowed.includes(m));
+  return { enabled: methods.length > 0, methods };
+}
+
+module.exports = { normalizeConfig };

package/src/generators/aliasResolver.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const { relativeImport } = require("./paths");
+const { specifier } = require("./syntax");
+const { allAliasEntries } = require("../config/aliases");
+
+function normalizeSlashes(p) {
+  return p.split("\\").join("/");
+}
+
+/**
+ * Finds the alias whose target directory is the deepest (most specific) match for
+ * `targetPathNoExt` — e.g. for "src/configs/db/index" this prefers "@db" (src/configs/db) over
+ * the root "@" (src), even though both technically match.
+ */
+function findLongestAliasMatch(aliasConfig, targetPathNoExt) {
+  const target = normalizeSlashes(targetPathNoExt);
+  let best = null;
+
+  for (const [key, dir] of Object.entries(allAliasEntries(aliasConfig))) {
+    const normalizedDir = normalizeSlashes(dir).replace(/^\.\/?$/, "");
+    const isRoot = normalizedDir === "";
+    const prefix = isRoot ? "" : `${normalizedDir}/`;
+
+    const matches = isRoot ? true : target === normalizedDir || target.startsWith(prefix);
+    if (!matches) continue;
+
+    const dirLen = isRoot ? 0 : normalizedDir.length;
+    if (!best || dirLen > best.dirLen) {
+      const remainder = isRoot ? target : target.slice(normalizedDir.length).replace(/^\//, "");
+      best = { key, dirLen, remainder };
+    }
+  }
+
+  return best;
+}
+
+/**
+ * The one place that decides how a generated file imports another generated file. Falls back to
+ * the pre-existing relative-path behavior whenever aliases are disabled, the two files are in the
+ * same directory (aliasing a sibling import adds noise, not clarity), or — defensively — no alias
+ * covers the target at all.
+ *
+ * @param config normalized project config
+ * @param aliasConfig result of buildAliasConfig() (or {enabled:false} / undefined)
+ * @param fromDir directory (relative to project root) of the file doing the importing
+ * @param targetPathNoExt path (relative to project root, no extension) of the file being imported
+ */
+function resolveImportPath(config, aliasConfig, fromDir, targetPathNoExt) {
+  const plainRelative = relativeImport(fromDir, targetPathNoExt);
+  const isSameDirectory = plainRelative.startsWith("./") && !plainRelative.slice(2).includes("/");
+
+  if (isSameDirectory || !aliasConfig || !aliasConfig.enabled) {
+    return specifier(config, plainRelative);
+  }
+
+  const hit = findLongestAliasMatch(aliasConfig, targetPathNoExt);
+  if (!hit) return specifier(config, plainRelative); // defensive: every real dir GAZAN writes to has an alias
+
+  const aliasSpecifier = hit.remainder ? `${hit.key}/${hit.remainder}` : hit.key;
+  // Under native ESM (moduleSystem "mjs"), both Node's own resolution and TypeScript's NodeNext
+  // resolver require an explicit extension even on path-mapped/alias specifiers — the same rule
+  // specifier() already applies to plain relative imports, so reuse it here rather than assuming
+  // "aliases never need extensions" (that's only true for CJS resolution and module-alias).
+  return specifier(config, aliasSpecifier);
+}
+
+module.exports = { resolveImportPath, findLongestAliasMatch };

package/src/generators/aliasRuntime.js

@@ -0,0 +1,79 @@
+"use strict";
+
+const { allAliasEntries, toTsPaths } = require("../config/aliases");
+
+/**
+ * package.json `_moduleAliases` fragment consumed by the `module-alias` package — CJS+JS only.
+ * `module-alias/register` (required as the first line of server.js) reads this at process start.
+ */
+function buildModuleAliasPackageFragment(aliasConfig) {
+  return { _moduleAliases: allAliasEntries(aliasConfig) };
+}
+
+/**
+ * alias-loader.mjs — a small custom ESM loader hook for MJS+JS, where neither `module-alias`
+ * (CJS-require-only) nor TypeScript's `paths` (type-checking only, not a runtime mechanism) apply.
+ * Registered via `node --experimental-loader=./alias-loader.mjs`. Intercepts only bare `@...`
+ * specifiers; everything else passes straight through to Node's normal resolution.
+ */
+function generateAliasLoaderFile(aliasConfig) {
+  const entries = allAliasEntries(aliasConfig);
+  const aliasLiteral = JSON.stringify(entries, null, 2);
+
+  return `// Generated by GAZAN. Resolves the project's @-prefixed import aliases for native ESM,
+// where neither module-alias (CommonJS-only) nor TypeScript's "paths" (type-checking only) apply.
+// Registered via: node --experimental-loader=./alias-loader.mjs
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const ALIASES = ${aliasLiteral};
+
+// Longest target first, so a more specific alias (e.g. "@db") is tried before a shorter one
+// that would also match (e.g. the root "@").
+const sortedAliases = Object.entries(ALIASES).sort((a, b) => b[1].length - a[1].length);
+
+const projectRoot = fileURLToPath(new URL(".", import.meta.url));
+
+export async function resolve(specifier, context, nextResolve) {
+  for (const [alias, dir] of sortedAliases) {
+    if (specifier === alias || specifier.startsWith(\`\${alias}/\`)) {
+      const rest = specifier.slice(alias.length).replace(/^\\//, "");
+      let resolvedPath = path.join(projectRoot, dir, rest);
+      // Generated specifiers already carry .js, but resolve defensively for any that don't
+      // (native ESM has no extension-guessing of its own).
+      if (!path.extname(resolvedPath)) resolvedPath += ".js";
+      return nextResolve(pathToFileURL(resolvedPath).href, context);
+    }
+  }
+  return nextResolve(specifier, context);
+}
+`;
+}
+
+/** tsconfig.json paths fragment — merged into the base tsconfig by the tsconfig generator. */
+function buildTsconfigAliasFragment(aliasConfig) {
+  return toTsPaths(aliasConfig);
+}
+
+/**
+ * jsconfig.json — plain JS projects get no TypeScript compiler, but VS Code (and most editors)
+ * read jsconfig.json for path-alias-aware intellisense/go-to-definition. Purely a DX aid; it has
+ * no effect on how the generated project actually runs (module-alias / the MJS loader do that).
+ */
+function buildJsconfigJson(aliasConfig) {
+  const { baseUrl, paths } = toTsPaths(aliasConfig);
+  return {
+    compilerOptions: {
+      baseUrl,
+      paths,
+    },
+    exclude: ["node_modules", "dist"],
+  };
+}
+
+module.exports = {
+  buildModuleAliasPackageFragment,
+  generateAliasLoaderFile,
+  buildTsconfigAliasFragment,
+  buildJsconfigJson,
+};

package/src/generators/database/mongoNative.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const { isEsm } = require("../syntax");
+const { sharedDir } = require("../paths");
+const { resolveImportPath } = require("../aliasResolver");
+
+/** configs/db/index.{js,ts} — centralized native MongoDB driver client lifecycle. */
+function generateMongoNativeDbConfig(config, aliasConfig) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const fromDir = `${sharedDir(config, "configs")}/db`;
+  const envPath = resolveImportPath(config, aliasConfig, fromDir, `${sharedDir(config, "helpers")}/env`);
+
+  const imports = esm ? `import { MongoClient } from "mongodb";` : `const { MongoClient } = require("mongodb");`;
+  const envImport = esm ? `import { env } from "${envPath}";` : `const { env } = require("${envPath}");`;
+
+  return `${imports}
+${envImport}
+
+const client = new MongoClient(env.MONGODB_URI);
+let db${isTs ? ": import(\"mongodb\").Db | undefined" : ""};
+let connected = false;
+
+async function connect() {
+  if (connected) return;
+  await client.connect();
+  db = client.db();
+  connected = true;
+  console.log("[db] mongodb connected");
+}
+
+function getDb() {
+  if (!db) throw new Error("Database not connected. Call connect() first.");
+  return db;
+}
+
+async function disconnect() {
+  await client.close();
+}
+
+${esm ? "export { client, getDb, connect, disconnect };" : "module.exports = { client, getDb, connect, disconnect };"}
+`;
+}
+
+module.exports = { generateMongoNativeDbConfig };

package/src/generators/database/mongoose.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const { isEsm } = require("../syntax");
+const { sharedDir } = require("../paths");
+const { resolveImportPath } = require("../aliasResolver");
+
+/** configs/db/index.{js,ts} — centralized Mongoose connection lifecycle. */
+function generateMongooseDbConfig(config, aliasConfig) {
+  const esm = isEsm(config);
+  const fromDir = `${sharedDir(config, "configs")}/db`;
+  const envPath = resolveImportPath(config, aliasConfig, fromDir, `${sharedDir(config, "helpers")}/env`);
+
+  const imports = esm ? `import mongoose from "mongoose";` : `const mongoose = require("mongoose");`;
+  const envImport = esm ? `import { env } from "${envPath}";` : `const { env } = require("${envPath}");`;
+
+  return `${imports}
+${envImport}
+
+async function connect() {
+  await mongoose.connect(env.MONGODB_URI);
+  console.log("[db] mongodb connected");
+}
+
+async function disconnect() {
+  await mongoose.disconnect();
+}
+
+${esm ? "export { mongoose, connect, disconnect };" : "module.exports = { mongoose, connect, disconnect };"}
+`;
+}
+
+module.exports = { generateMongooseDbConfig };