gazan-init 0.1.0

package/src/generators/packageJson.js

@@ -0,0 +1,107 @@
+"use strict";
+
+const { baseDir } = require("./paths");
+
+function entryPath(config) {
+  const base = baseDir(config);
+  const file = `server.${config.language}`;
+  return base === "." ? file : `${base}/${file}`;
+}
+
+function buildPackageJson(config) {
+  const dependencies = {
+    express: "^4.21.1",
+    dotenv: "^16.4.5",
+    zod: "^3.23.8",
+    cors: "^2.8.5",
+    helmet: "^7.1.0",
+    "express-rate-limit": "^7.4.1",
+  };
+  const devDependencies = {};
+
+  if (config.redis) {
+    dependencies.ioredis = "^5.4.1";
+  }
+  if (config.rateLimitStrategy === "redis") {
+    dependencies["rate-limit-redis"] = "^4.2.0";
+  }
+  if (config.bullMQ) {
+    dependencies.bullmq = "^5.21.2";
+  }
+  if (config.socketIO) {
+    dependencies["socket.io"] = "^4.8.0";
+  }
+  if (config.database.type === "postgresql" && config.database.orm === "prisma") {
+    dependencies["@prisma/client"] = "^5.20.0";
+    devDependencies.prisma = "^5.20.0";
+  }
+  if (config.database.type === "mongodb" && config.database.orm === "mongoose") {
+    dependencies.mongoose = "^8.7.0";
+  }
+  if (config.database.type === "mongodb" && config.database.orm === "native") {
+    dependencies.mongodb = "^6.9.0";
+  }
+  if (config.authentication.enabled && config.authentication.methods.includes("email-password")) {
+    dependencies.bcrypt = "^5.1.1";
+  }
+  if (
+    config.authentication.enabled &&
+    (config.authentication.methods.includes("jwt") || config.authentication.methods.includes("refresh-token"))
+  ) {
+    dependencies.jsonwebtoken = "^9.0.2";
+  }
+  // Deliberately no OAuth dependency here — see helpers/oauth.stub.{js,ts} and the README's
+  // Authentication section. GAZAN scaffolds OAuth env vars only; picking and wiring a provider
+  // (and its client library) is left to the project, since "OAuth" isn't one integration.
+
+  if (config.language === "ts") {
+    devDependencies.typescript = "^5.6.3";
+    devDependencies.tsx = "^4.19.1";
+    devDependencies["@types/node"] = "^22.7.5";
+    devDependencies["@types/express"] = "^4.17.21";
+    devDependencies["@types/cors"] = "^2.8.17";
+    if (dependencies.bcrypt) devDependencies["@types/bcrypt"] = "^5.0.2";
+    if (dependencies.jsonwebtoken) devDependencies["@types/jsonwebtoken"] = "^9.0.7";
+  }
+
+  const entry = entryPath(config);
+  const scripts = {
+    start: config.language === "ts" ? "node dist/server.js" : `node ${entry}`,
+    dev: config.language === "ts" ? `tsx watch ${entry}` : `node --watch ${entry}`,
+  };
+
+  if (config.language === "ts") {
+    scripts.build = "tsc";
+  }
+
+  if (config.database.type === "postgresql" && config.database.orm === "prisma") {
+    scripts["db:generate"] = "prisma generate";
+    scripts["db:migrate"] = "prisma migrate dev";
+    scripts["db:push"] = "prisma db push";
+    scripts["db:studio"] = "prisma studio";
+  }
+
+  const pkg = {
+    name: config.projectName,
+    version: "0.1.0",
+    private: true,
+    type: config.moduleSystem === "mjs" ? "module" : "commonjs",
+    main: entry,
+    scripts,
+    dependencies: sortKeys(dependencies),
+  };
+
+  if (Object.keys(devDependencies).length > 0) {
+    pkg.devDependencies = sortKeys(devDependencies);
+  }
+
+  return pkg;
+}
+
+function sortKeys(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) sorted[key] = obj[key];
+  return sorted;
+}
+
+module.exports = { buildPackageJson, entryPath };

package/src/generators/paths.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const path = require("path");
+
+function baseDir(config) {
+  return config.useSrc ? "src" : ".";
+}
+
+function sharedDir(config, name) {
+  return path.join(baseDir(config), name);
+}
+
+/**
+ * Architecture-aware locations for controller/route/service/validator files.
+ * MVC: flat, shared folders. HMVC: grouped per entity module.
+ */
+function archDirs(config, moduleName) {
+  const base = baseDir(config);
+  if (config.architecture === "hmvc") {
+    const moduleBase = path.join(base, "modules", moduleName);
+    return {
+      controllers: path.join(moduleBase, "controllers"),
+      routes: path.join(moduleBase, "routes"),
+      services: path.join(moduleBase, "services"),
+      validators: path.join(moduleBase, "validators"),
+      moduleBase,
+    };
+  }
+  return {
+    controllers: path.join(base, "controllers"),
+    routes: path.join(base, "routes"),
+    services: path.join(base, "services"),
+    validators: path.join(base, "validators"),
+    moduleBase: base,
+  };
+}
+
+/** Relative import path (POSIX, no extension) from `fromDir` to `toFile` (also relative to project root, no extension). */
+function relativeImport(fromDir, toFileNoExt) {
+  let rel = path.relative(fromDir, toFileNoExt).split(path.sep).join("/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel;
+}
+
+module.exports = { baseDir, sharedDir, archDirs, relativeImport };

package/src/generators/project.js

@@ -0,0 +1,189 @@
+"use strict";
+
+const { isEsm } = require("./syntax");
+const { baseDir, sharedDir, archDirs } = require("./paths");
+const { resolveImportPath } = require("./aliasResolver");
+
+function generateAppFile(config, aliasConfig) {
+  const esm = isEsm(config);
+  const base = baseDir(config);
+  const r = (target) => resolveImportPath(config, aliasConfig, base, target);
+
+  const imports = [];
+  imports.push(esm ? `import express from "express";` : `const express = require("express");`);
+  imports.push(esm ? `import cors from "cors";` : `const cors = require("cors");`);
+  imports.push(esm ? `import helmet from "helmet";` : `const helmet = require("helmet");`);
+  const envPath = r(`${sharedDir(config, "helpers")}/env`);
+  imports.push(esm ? `import { env } from "${envPath}";` : `const { env } = require("${envPath}");`);
+  const rateLimitPath = r(`${sharedDir(config, "middlewares")}/rate-limit`);
+  imports.push(
+    esm ? `import { rateLimiter } from "${rateLimitPath}";` : `const { rateLimiter } = require("${rateLimitPath}");`
+  );
+  const notFoundPath = r(`${sharedDir(config, "middlewares")}/not-found`);
+  imports.push(esm ? `import { notFound } from "${notFoundPath}";` : `const { notFound } = require("${notFoundPath}");`);
+  const errorHandlerPath = r(`${sharedDir(config, "middlewares")}/error-handler`);
+  imports.push(
+    esm
+      ? `import { errorHandler } from "${errorHandlerPath}";`
+      : `const { errorHandler } = require("${errorHandlerPath}");`
+  );
+  const routesPath = r(`${sharedDir(config, "routes")}/index`);
+  imports.push(esm ? `import routes from "${routesPath}";` : `const routes = require("${routesPath}");`);
+
+  const body = `if (env.NODE_ENV === "production" && env.CORS_ORIGIN === "*") {
+  // CORS_ORIGIN="*" is fine for local development but should never ship to production —
+  // lock it down to your actual frontend origin(s) via the CORS_ORIGIN env var.
+  console.warn("[security] CORS_ORIGIN is \\"*\\" in production — restrict it to your real origin(s).");
+}
+
+const app = express();
+
+app.use(helmet());
+app.use(cors({ origin: env.CORS_ORIGIN }));
+app.use(express.json({ limit: "1mb" }));
+app.use(express.urlencoded({ extended: true, limit: "1mb" }));
+app.use(rateLimiter);
+
+app.get("/health", (req, res) => {
+  res.status(200).json({ success: true, data: { status: "ok" } });
+});
+
+app.use("/api", routes);
+
+app.use(notFound);
+app.use(errorHandler);
+`;
+
+  const footer = esm ? "\nexport default app;\n" : "\nmodule.exports = app;\n";
+
+  return `${imports.join("\n")}\n\n${body}${footer}`;
+}
+
+function generateServerFile(config, aliasConfig) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const base = baseDir(config);
+  const r = (target) => resolveImportPath(config, aliasConfig, base, target);
+
+  // CJS+JS is the one combination where aliases need an explicit runtime registration call —
+  // TS relies on tsc-alias (build) / tsx (dev), and MJS+JS on a --experimental-loader flag, but
+  // module-alias must be required before anything else in the process resolves a module.
+  const moduleAliasRegister =
+    aliasConfig && aliasConfig.enabled && config.language === "js" && config.moduleSystem === "cjs"
+      ? `require("module-alias/register");\n\n`
+      : "";
+
+  const imports = [];
+  imports.push(esm ? `import http from "http";` : `const http = require("http");`);
+  const appPath = r(`${base}/app`);
+  imports.push(esm ? `import app from "${appPath}";` : `const app = require("${appPath}");`);
+  const envPath = r(`${sharedDir(config, "helpers")}/env`);
+  imports.push(esm ? `import { env } from "${envPath}";` : `const { env } = require("${envPath}");`);
+  const shutdownPath = r(`${sharedDir(config, "utils")}/shutdown`);
+  imports.push(
+    esm ? `import { createShutdown } from "${shutdownPath}";` : `const { createShutdown } = require("${shutdownPath}");`
+  );
+  const processEventsPath = r(`${sharedDir(config, "helpers")}/process-events`);
+  imports.push(
+    esm
+      ? `import { registerProcessEvents } from "${processEventsPath}";`
+      : `const { registerProcessEvents } = require("${processEventsPath}");`
+  );
+
+  if (config.database.type !== "none") {
+    const dbPath = r(`${sharedDir(config, "configs")}/db/index`);
+    imports.push(esm ? `import * as db from "${dbPath}";` : `const db = require("${dbPath}");`);
+  }
+  if (config.redis) {
+    const redisPath = r(`${sharedDir(config, "configs")}/redis/index`);
+    imports.push(
+      esm ? `import { redisClient } from "${redisPath}";` : `const { redisClient } = require("${redisPath}");`
+    );
+  }
+  if (config.socketIO) {
+    const socketPath = r(`${sharedDir(config, "socket")}/index`);
+    imports.push(
+      esm ? `import { createSocketServer } from "${socketPath}";` : `const { createSocketServer } = require("${socketPath}");`
+    );
+  }
+  if (config.bullMQ) {
+    const workersPath = r(`${sharedDir(config, "workers")}/index`);
+    imports.push(
+      esm ? `import { queues, workers } from "${workersPath}";` : `const { queues, workers } = require("${workersPath}");`
+    );
+  }
+
+  const bootLines = [];
+  bootLines.push(`const httpServer = http.createServer(app);`);
+  if (config.socketIO) {
+    bootLines.push(`const io = createSocketServer(httpServer);`);
+  }
+
+  const shutdownResourceLines = [`    httpServer,`];
+  if (config.socketIO) {
+    shutdownResourceLines.push(`    io: { close: () => new Promise((resolve) => io.close(() => resolve())) },`);
+  }
+  if (config.bullMQ) {
+    shutdownResourceLines.push(`    workers,`);
+    shutdownResourceLines.push(`    queues,`);
+  }
+  if (config.redis) {
+    shutdownResourceLines.push(`    redis: redisClient,`);
+  }
+  if (config.database.type !== "none") {
+    shutdownResourceLines.push(`    db,`);
+  }
+
+  const dbConnectCall = config.database.type !== "none" ? `  await db.connect();\n` : "";
+
+  const body = `async function start()${isTs ? ": Promise<void>" : ""} {
+${dbConnectCall}
+${bootLines.map((l) => "  " + l).join("\n")}
+
+  const shutdown = createShutdown({
+${shutdownResourceLines.join("\n")}
+  });
+
+  registerProcessEvents(shutdown);
+
+  httpServer.listen(env.PORT, () => {
+    console.log(\`[server] listening on port \${env.PORT} (\${env.NODE_ENV})\`);
+  });
+}
+
+start().catch((error) => {
+  console.error("[server] failed to start:", error);
+  process.exit(1);
+});
+`;
+
+  return `${moduleAliasRegister}${imports.join("\n")}\n\n${body}`;
+}
+
+function generateRoutesIndex(config, aliasConfig, models) {
+  const esm = isEsm(config);
+  const fromDir = sharedDir(config, "routes");
+  const imports = [esm ? `import { Router } from "express";` : `const { Router } = require("express");`];
+
+  const useLines = [];
+  for (const model of models) {
+    const varName = `${model.camelName}Routes`;
+    const targetDir = archDirs(config, model.camelName).routes;
+    const importPath = resolveImportPath(config, aliasConfig, fromDir, `${targetDir}/${model.kebabName}.routes`);
+    imports.push(
+      esm ? `import ${varName} from "${importPath}";` : `const ${varName} = require("${importPath}");`
+    );
+    useLines.push(`router.use("/${model.routePath}", ${varName});`);
+  }
+
+  const body = `const router = Router();
+
+${useLines.join("\n")}
+`;
+
+  const footer = esm ? "\nexport default router;\n" : "\nmodule.exports = router;\n";
+
+  return `${imports.join("\n")}\n\n${body}${footer}`;
+}
+
+module.exports = { generateAppFile, generateServerFile, generateRoutesIndex };

package/src/generators/readme.js

@@ -0,0 +1,177 @@
+"use strict";
+
+const { buildEnvSpec } = require("./env");
+const { getSensitiveFields } = require("./entity/sensitiveFields");
+const { allAliasEntries } = require("../config/aliases");
+
+function buildReadme(config, aliasConfig, entityModel) {
+  const lines = [];
+  lines.push(`# ${config.projectName}`, "");
+  lines.push("Generated with [GAZAN](https://github.com/) — an interactive backend project initializer.", "");
+
+  lines.push("## Stack", "");
+  lines.push(`- Module system: **${config.moduleSystem.toUpperCase()}**`);
+  lines.push(`- Language: **${config.language === "ts" ? "TypeScript" : "JavaScript"}**`);
+  lines.push(`- Architecture: **${config.architecture.toUpperCase()}**`);
+  lines.push(`- Source layout: ${config.useSrc ? "`src/`" : "project root"}`);
+  if (config.database.type !== "none") {
+    lines.push(`- Database: **${config.database.type}** (${config.database.orm})`);
+  } else {
+    lines.push(`- Database: none`);
+  }
+  if (config.redis) lines.push(`- Redis: enabled`);
+  if (config.bullMQ) lines.push(`- BullMQ workers: enabled`);
+  if (config.socketIO) lines.push(`- Socket.IO: enabled`);
+  if (config.authentication.enabled) {
+    lines.push(`- Authentication: ${config.authentication.methods.join(", ")}`);
+  }
+  if (aliasConfig && aliasConfig.enabled) lines.push(`- Import aliases: enabled`);
+  lines.push("");
+
+  if (config.authentication.enabled && config.authentication.methods.includes("oauth")) {
+    lines.push("> **OAuth is a stub.** Only env vars and `helpers/oauth.stub.*` (a documented");
+    lines.push("> `throw`, not a working integration) are generated — no provider, client");
+    lines.push("> library, or routes. See that file for what to build.");
+    lines.push("");
+  }
+
+  lines.push("## Project structure", "");
+  lines.push("```");
+  lines.push(...buildStructureTree(config));
+  lines.push("```", "");
+
+  if (aliasConfig && aliasConfig.enabled) {
+    lines.push("## Import Aliases", "");
+    lines.push("This project uses module aliases.", "");
+    const entries = Object.entries(allAliasEntries(aliasConfig));
+    const widest = Math.max(...entries.map(([key]) => key.length));
+    for (const [key, target] of entries) {
+      lines.push(`${key.padEnd(widest)}  → ${target}`);
+    }
+    lines.push("");
+    const runtimeNote =
+      config.language === "ts"
+        ? "Resolved via tsconfig `paths` at dev time (`tsx`), and rewritten to relative paths after `tsc` by `tsc-alias` at build time."
+        : config.moduleSystem === "mjs"
+        ? "Resolved at runtime by the generated `alias-loader.mjs`, registered via `node --experimental-loader=./alias-loader.mjs` (already wired into `npm run dev` / `npm start`)."
+        : "Resolved at runtime by `module-alias` (registered as the first line of the entry file) from the `_moduleAliases` field in `package.json`.";
+    lines.push(`> ${runtimeNote}`, "");
+
+    const exampleEntry = entries.find(([key]) => key !== aliasConfig.root) || entries[0];
+    if (exampleEntry) {
+      lines.push("```ts");
+      lines.push(`import x from '${exampleEntry[0]}/example';`);
+      lines.push("```", "");
+    }
+  }
+
+  lines.push("## Environment variables", "");
+  lines.push("| Variable | Description |", "|---|---|");
+  for (const v of buildEnvSpec(config)) {
+    lines.push(`| \`${v.name}\` | example: \`${v.example}\` |`);
+  }
+  lines.push("");
+
+  lines.push("## Development", "");
+  lines.push("```bash");
+  lines.push("npm install");
+  lines.push("cp .env.example .env");
+  if (config.database.type === "postgresql" && config.database.orm === "prisma") {
+    lines.push("npm run db:generate");
+    lines.push("npm run db:migrate");
+  }
+  lines.push("npm run dev");
+  lines.push("```", "");
+
+  lines.push("## Production", "");
+  lines.push("```bash");
+  if (config.language === "ts") {
+    lines.push("npm run build");
+  }
+  lines.push("npm start");
+  lines.push("```", "");
+
+  if (config.database.type === "postgresql" && config.database.orm === "prisma") {
+    lines.push("## Database commands", "");
+    lines.push("```bash");
+    lines.push("npm run db:generate   # regenerate the Prisma client");
+    lines.push("npm run db:migrate    # run dev migrations");
+    lines.push("npm run db:push       # push schema without a migration");
+    lines.push("npm run db:studio     # open Prisma Studio");
+    lines.push("```", "");
+  }
+
+  if (entityModel && entityModel.models.length > 0) {
+    lines.push("## Generated entities", "");
+    for (const model of entityModel.models) {
+      lines.push(`- **${model.pascalName}** — \`/api/${model.routePath}\``);
+    }
+    lines.push("");
+
+    const sensitiveModels = entityModel.models.filter((m) => getSensitiveFields(m).length > 0);
+    if (sensitiveModels.length > 0) {
+      lines.push(
+        `> Fields matching \`password\`/\`secret\`/\`hash\` (${sensitiveModels
+          .map((m) => `${m.pascalName}.${getSensitiveFields(m).join(", ")}`)
+          .join("; ")}) are stripped from every generated response automatically.`
+      );
+      lines.push("");
+    }
+
+    const hasManyToMany = entityModel.models.some((m) => m.relations.some((r) => r.type === "belongsToMany"));
+    if (hasManyToMany) {
+      lines.push(
+        "> One or more entities use a many-to-many (`belongsToMany`) relation. It's represented in the"
+      );
+      lines.push(
+        "> generated schema/model, but the generated CRUD create/update endpoints don't read or write it —"
+      );
+      lines.push("> manage those joins via your own service code.");
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function buildStructureTree(config) {
+  const base = config.useSrc ? "src/" : "";
+  const lines = [`${config.projectName}/`];
+  if (config.useSrc) lines.push("├── src/");
+  const indent = config.useSrc ? "│   " : "";
+
+  if (config.architecture === "mvc") {
+    lines.push(`${indent}├── controllers/`);
+    lines.push(`${indent}├── routes/`);
+    lines.push(`${indent}├── services/`);
+    lines.push(`${indent}├── validators/`);
+  } else {
+    lines.push(`${indent}├── modules/`);
+    lines.push(`${indent}│   └── <entity>/`);
+    lines.push(`${indent}│       ├── controllers/`);
+    lines.push(`${indent}│       ├── routes/`);
+    lines.push(`${indent}│       ├── services/`);
+    lines.push(`${indent}│       └── validators/`);
+  }
+  lines.push(`${indent}├── middlewares/`);
+  lines.push(`${indent}├── helpers/`);
+  lines.push(`${indent}├── utils/`);
+  lines.push(`${indent}├── configs/`);
+  if (config.database.type !== "none") lines.push(`${indent}│   └── db/`);
+  if (config.redis) lines.push(`${indent}│   └── redis/`);
+  if (config.bullMQ) lines.push(`${indent}├── workers/`);
+  if (config.socketIO) lines.push(`${indent}├── socket/`);
+  lines.push(`${indent}├── app.${config.language}`);
+  lines.push(`${indent}└── server.${config.language}`);
+  if (config.database.type === "postgresql" && config.database.orm === "prisma") {
+    lines.push("├── prisma/");
+    lines.push("│   └── schema.prisma");
+  }
+  lines.push("├── .env.example");
+  lines.push("├── package.json");
+  lines.push("└── README.md");
+
+  return lines;
+}
+
+module.exports = { buildReadme };

package/src/generators/shutdown.js

@@ -0,0 +1,113 @@
+"use strict";
+
+const { isEsm } = require("./syntax");
+
+/**
+ * Generic, idempotent graceful-shutdown orchestrator. It knows nothing about
+ * which features are enabled — server.js wires in only the resources that
+ * actually exist, so a resource that was never enabled is never touched.
+ */
+function generateShutdownFile(config) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+
+  const typeBlock = isTs
+    ? `export interface ShutdownResources {
+  httpServer?: { close: (cb: (err?: Error) => void) => void };
+  io?: { close: () => Promise<void> | void };
+  workers?: Array<{ close: () => Promise<void> }>;
+  queues?: Array<{ close: () => Promise<void> }>;
+  redis?: { quit: () => Promise<unknown> };
+  db?: { disconnect?: () => Promise<void>; close?: () => Promise<void> };
+}
+
+`
+    : "";
+
+  const fnSignature = isTs ? "createShutdown(resources: ShutdownResources = {})" : "createShutdown(resources = {})";
+
+  const body = `${typeBlock}function ${fnSignature} {
+  let shuttingDown = false;
+
+  return async function shutdown(signal${isTs ? ": string" : ""} = "SIGTERM") {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    console.log(\`\\n[shutdown] received \${signal}, closing resources...\`);
+
+    if (resources.httpServer) {
+      const server = resources.httpServer;
+      await new Promise((resolve) => server.close(() => resolve(undefined)));
+      console.log("[shutdown] http server closed");
+    }
+
+    if (resources.io) {
+      await resources.io.close();
+      console.log("[shutdown] socket.io closed");
+    }
+
+    if (resources.workers && resources.workers.length > 0) {
+      await Promise.all(resources.workers.map((worker) => worker.close()));
+      console.log("[shutdown] bullmq workers closed");
+    }
+
+    if (resources.queues && resources.queues.length > 0) {
+      await Promise.all(resources.queues.map((queue) => queue.close()));
+      console.log("[shutdown] bullmq queues closed");
+    }
+
+    if (resources.redis) {
+      await resources.redis.quit();
+      console.log("[shutdown] redis connection closed");
+    }
+
+    if (resources.db) {
+      if (resources.db.disconnect) await resources.db.disconnect();
+      else if (resources.db.close) await resources.db.close();
+      console.log("[shutdown] database connection closed");
+    }
+
+    console.log("[shutdown] complete");
+    process.exit(0);
+  };
+}
+
+${esm ? "export { createShutdown };" : "module.exports = { createShutdown };"}
+`;
+
+  return body;
+}
+
+function generateProcessEventsFile(config, shutdownImportPath) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const shutdownImport = esm
+    ? `import type { createShutdown } from "${shutdownImportPath}";`
+    : "";
+
+  const fnSignature = isTs
+    ? "registerProcessEvents(shutdown: ReturnType<typeof createShutdown>)"
+    : "registerProcessEvents(shutdown)";
+
+  const body = `${isTs && shutdownImport ? shutdownImport + "\n\n" : ""}function ${fnSignature} {
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  process.on("uncaughtException", (error) => {
+    console.error("[process] uncaught exception:", error);
+    shutdown("uncaughtException");
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    console.error("[process] unhandled rejection:", reason);
+    shutdown("unhandledRejection");
+  });
+}
+
+${esm ? "export { registerProcessEvents };" : "module.exports = { registerProcessEvents };"}
+`;
+
+  return body;
+}
+
+module.exports = { generateShutdownFile, generateProcessEventsFile };

package/src/generators/stripSensitiveFieldsHelper.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const { isEsm } = require("./syntax");
+
+/**
+ * helpers/strip-sensitive-fields.{js,ts} — generated only when at least one entity.json model has
+ * a field matching the sensitive-field heuristic (password/secret/hash). Services for those models
+ * use this to keep such fields out of API responses without touching every ORM's query layer.
+ *
+ * `T extends object` (rather than `Record<string, unknown>`) so this also accepts ORM-specific
+ * result types without an index signature (e.g. Mongoose Documents, Prisma model types) — the
+ * internal cast is the narrow, deliberate escape hatch generic "delete an arbitrary key" needs.
+ */
+function generateStripSensitiveFieldsHelper(config) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+
+  const singleSig = isTs
+    ? "stripSensitiveFields<T extends object>(record: T | null | undefined, fields: string[]): T | null | undefined"
+    : "stripSensitiveFields(record, fields)";
+  const listSig = isTs
+    ? "stripSensitiveFieldsFromList<T extends object>(records: T[], fields: string[]): T[]"
+    : "stripSensitiveFieldsFromList(records, fields)";
+  const cast = isTs ? " as Record<string, unknown>" : "";
+  const returnCast = isTs ? " as T" : "";
+
+  return `function ${singleSig} {
+  if (!record) return record;
+  const clone = { ...record }${cast};
+  for (const field of fields) {
+    delete clone[field];
+  }
+  return clone${returnCast};
+}
+
+function ${listSig} {
+  return records.map((record) => {
+    const clone = { ...record }${cast};
+    for (const field of fields) {
+      delete clone[field];
+    }
+    return clone${returnCast};
+  });
+}
+
+${esm ? "export { stripSensitiveFields, stripSensitiveFieldsFromList };" : "module.exports = { stripSensitiveFields, stripSensitiveFieldsFromList };"}
+`;
+}
+
+module.exports = { generateStripSensitiveFieldsHelper };