gazan-init 0.1.0

package/src/generators/entity/toPrisma.js

@@ -0,0 +1,233 @@
+"use strict";
+
+const { pluralize } = require("../../utils/strings");
+
+/**
+ * Normalized entity model -> Prisma schema string.
+ * entity.json -> Entity Parser -> Normalized Entity Model -> (this) Database Generator
+ */
+
+const PRISMA_TYPE_MAP = {
+  string: "String",
+  text: "String",
+  number: "Float",
+  integer: "Int",
+  float: "Float",
+  boolean: "Boolean",
+  date: "DateTime",
+  datetime: "DateTime",
+  uuid: "String",
+  json: "Json",
+  enum: null, // resolved to the generated enum name
+  decimal: "Decimal",
+  bigint: "BigInt",
+};
+
+function fieldEnumName(modelName, fieldName) {
+  return `${modelName}${fieldName.charAt(0).toUpperCase()}${fieldName.slice(1)}`;
+}
+
+function buildPrismaField(model, field) {
+  const parts = [field.name];
+  const prismaType = field.type === "enum" ? fieldEnumName(model.pascalName, field.name) : PRISMA_TYPE_MAP[field.type];
+  let typeStr = prismaType;
+  // Primary keys are always non-optional in Prisma regardless of the entity.json 'required' flag.
+  if (!field.primaryKey && (!field.required || field.nullable)) {
+    typeStr += "?";
+  }
+  parts.push(typeStr);
+
+  const attrs = [];
+  if (field.primaryKey) {
+    attrs.push("@id");
+  }
+  if (field.type === "uuid" && field.default === "uuid") {
+    attrs.push("@default(uuid())");
+  } else if (field.autoIncrement) {
+    attrs.push("@default(autoincrement())");
+  } else if ((field.type === "date" || field.type === "datetime") && field.default === "now") {
+    attrs.push("@default(now())");
+  } else if (field.default !== undefined && field.default !== null && field.default !== "uuid") {
+    attrs.push(`@default(${formatDefault(field)})`);
+  } else if (field.type === "datetime" && field.name.toLowerCase() === "createdat" && !field.default) {
+    attrs.push("@default(now())");
+  }
+  if (field.unique) attrs.push("@unique");
+  if (field.length && (field.type === "string" || field.type === "text")) {
+    attrs.push(`@db.VarChar(${field.length})`);
+  }
+
+  if (attrs.length > 0) parts.push(attrs.join(" "));
+  return parts.join(" ");
+}
+
+function formatDefault(field) {
+  if (field.type === "boolean") return String(Boolean(field.default));
+  if (["number", "integer", "float", "decimal", "bigint"].includes(field.type)) return String(field.default);
+  if (field.type === "enum") return String(field.default);
+  return JSON.stringify(field.default);
+}
+
+function buildEnums(model) {
+  return model.fields
+    .filter((f) => f.type === "enum")
+    .map((f) => {
+      const enumName = fieldEnumName(model.pascalName, f.name);
+      const values = f.values.join("\n  ");
+      return `enum ${enumName} {\n  ${values}\n}`;
+    });
+}
+
+/**
+ * Deterministic Prisma @relation name for the FK identified by (modelHoldingForeignKey, foreignKey).
+ * Both the owning (belongsTo) side and the reverse (hasMany/hasOne/auto) side derive the same
+ * string independently from these two inputs, so they always pair up — including self-relations
+ * and multiple distinct relations between the same two models, which Prisma would otherwise
+ * reject as ambiguous.
+ */
+function relationKey(modelHoldingForeignKey, foreignKey) {
+  return `${modelHoldingForeignKey.pascalName}_${foreignKey}`;
+}
+
+/**
+ * Builds a lookup of every hasMany/hasOne relation explicitly declared anywhere in the schema,
+ * keyed by the (owner model holding the FK, foreignKey) pair it answers. Used so we never
+ * auto-generate a reverse field that duplicates one the user already wrote by hand.
+ */
+function indexExplicitReverses(allModels) {
+  const map = new Map();
+  for (const declaringModel of allModels) {
+    for (const relation of declaringModel.relations) {
+      if (relation.type !== "hasMany" && relation.type !== "hasOne") continue;
+      const owner = allModels.find((m) => m.name === relation.model);
+      if (!owner || !relation.foreignKey) continue;
+      map.set(relationKey(owner, relation.foreignKey), {
+        declaringModelName: declaringModel.name,
+        relationName: relation.name,
+      });
+    }
+  }
+  return map;
+}
+
+/**
+ * Counts, per (owner model, target model) pair, how many auto-derived (non-explicit) belongsTo
+ * relations need a reverse field — so that when there's more than one (e.g. Post.author and
+ * Post.editor both pointing at User), every reverse field is disambiguated, not just the 2nd+.
+ */
+function countAutoReversePairs(allModels, explicitReverses) {
+  const counts = new Map();
+  for (const owner of allModels) {
+    for (const relation of owner.relations) {
+      if (relation.type !== "belongsTo") continue;
+      const target = allModels.find((m) => m.name === relation.model);
+      if (!target) continue;
+      const key = relationKey(owner, relation.foreignKey);
+      if (explicitReverses.has(key)) continue;
+      const pairId = `${owner.name}->${target.name}`;
+      counts.set(pairId, (counts.get(pairId) || 0) + 1);
+    }
+  }
+  return counts;
+}
+
+/**
+ * Fields owned by `model` for its own declared relations (belongsTo/hasMany/hasOne/belongsToMany),
+ * plus any auto-derived reverse array fields this model needs to receive because some other model
+ * declared a belongsTo pointing at it without an explicit matching hasMany/hasOne.
+ */
+function buildRelationFields(model, allModels, explicitReverses, pairTotalCounts) {
+  const lines = [];
+
+  for (const relation of model.relations) {
+    const target = allModels.find((m) => m.name === relation.model);
+    if (!target) continue;
+
+    if (relation.type === "belongsTo") {
+      const key = relationKey(model, relation.foreignKey);
+      // The relation field's optionality must mirror the FK scalar's — Prisma rejects a required
+      // relation object backed by a nullable foreign key (and vice versa).
+      const fkField = model.fields.find((f) => f.name === relation.foreignKey);
+      const optional = !fkField || !fkField.required || fkField.nullable ? "?" : "";
+      lines.push(
+        `  ${relation.name} ${target.pascalName}${optional} @relation("${key}", fields: [${relation.foreignKey}], references: [${target.primaryKey.name}])`
+      );
+    } else if (relation.type === "hasMany") {
+      const key = relationKey(target, relation.foreignKey);
+      lines.push(`  ${relation.name} ${target.pascalName}[] @relation("${key}")`);
+    } else if (relation.type === "hasOne") {
+      const key = relationKey(target, relation.foreignKey);
+      lines.push(`  ${relation.name} ${target.pascalName}? @relation("${key}")`);
+    } else if (relation.type === "belongsToMany") {
+      lines.push(`  ${relation.name} ${target.pascalName}[] @relation("${relation.through}")`);
+    }
+  }
+
+  // Auto-derive the reverse side for every belongsTo (anywhere in the schema, including on this
+  // model itself for self-relations) that points at `model` and has no explicit hasMany/hasOne.
+  for (const owner of allModels) {
+    for (const relation of owner.relations) {
+      if (relation.type !== "belongsTo" || relation.model !== model.name) continue;
+
+      const key = relationKey(owner, relation.foreignKey);
+      if (explicitReverses.has(key)) continue; // user already declared this side by hand
+
+      const pairId = `${owner.name}->${model.name}`;
+      const base = pluralize(owner.camelName);
+      const needsDisambiguation = (pairTotalCounts.get(pairId) || 0) > 1;
+      const fieldName = needsDisambiguation ? `${base}As${relation.pascalName}` : base;
+
+      lines.push(`  ${fieldName} ${owner.pascalName}[] @relation("${key}")`);
+    }
+  }
+
+  return lines;
+}
+
+function generatePrismaSchema(entityModel, config) {
+  const provider = "postgresql";
+  const header = [
+    `generator client {`,
+    `  provider = "prisma-client-js"`,
+    `}`,
+    ``,
+    `datasource db {`,
+    `  provider = "${provider}"`,
+    `  url      = env("DATABASE_URL")`,
+    `}`,
+  ].join("\n");
+
+  const blocks = [];
+  const enumBlocks = [];
+  const explicitReverses = indexExplicitReverses(entityModel.models);
+  const pairTotalCounts = countAutoReversePairs(entityModel.models, explicitReverses);
+
+  for (const model of entityModel.models) {
+    const lines = [`model ${model.pascalName} {`];
+    for (const field of model.fields) {
+      lines.push(`  ${buildPrismaField(model, field)}`);
+    }
+    const relationLines = buildRelationFields(model, entityModel.models, explicitReverses, pairTotalCounts);
+    for (const line of relationLines) lines.push(line);
+
+    if (model.timestamps) {
+      lines.push(`  createdAt DateTime @default(now())`);
+      lines.push(`  updatedAt DateTime @updatedAt`);
+    }
+
+    const indexedFields = model.fields.filter((f) => f.index && !f.unique && !f.primaryKey);
+    for (const field of indexedFields) {
+      lines.push(`\n  @@index([${field.name}])`);
+    }
+
+    lines.push(`\n  @@map("${model.tableName}")`);
+    lines.push(`}`);
+    blocks.push(lines.join("\n"));
+
+    enumBlocks.push(...buildEnums(model));
+  }
+
+  return [header, ...enumBlocks, ...blocks].join("\n\n") + "\n";
+}
+
+module.exports = { generatePrismaSchema };

package/src/generators/entity/toZod.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const { isEsm } = require("../syntax");
+
+const ZOD_BASE = {
+  string: "z.string()",
+  text: "z.string()",
+  number: "z.number()",
+  integer: "z.number().int()",
+  float: "z.number()",
+  boolean: "z.boolean()",
+  date: "z.coerce.date()",
+  datetime: "z.coerce.date()",
+  uuid: "z.string().uuid()",
+  json: "z.record(z.string(), z.any())",
+  decimal: "z.number()",
+  bigint: "z.number().int()",
+};
+
+function buildFieldZod(field) {
+  if (field.type === "enum") {
+    let expr = `z.enum(${JSON.stringify(field.values)})`;
+    if (!field.required) expr += ".optional()";
+    if (field.nullable) expr += ".nullable()";
+    return expr;
+  }
+
+  let expr = ZOD_BASE[field.type];
+  if (field.type === "string" || field.type === "text") {
+    if (field.length) expr += `.max(${field.length})`;
+    if (field.min !== undefined) expr += `.min(${field.min})`;
+  } else if (["number", "integer", "float", "decimal", "bigint"].includes(field.type)) {
+    if (field.min !== undefined) expr += `.min(${field.min})`;
+    if (field.max !== undefined) expr += `.max(${field.max})`;
+  }
+
+  if (!field.required) expr += ".optional()";
+  if (field.nullable) expr += ".nullable()";
+  return expr;
+}
+
+/** entity model -> Zod create/update validators. Skips the primary key and timestamp fields on write payloads. */
+function generateEntityValidator(model, config) {
+  const esm = isEsm(config);
+  const zodImport = esm ? `import { z } from "zod";` : `const { z } = require("zod");`;
+
+  const writableFields = model.fields.filter((f) => !(f.primaryKey && f.synthetic));
+
+  const createLines = writableFields.map((f) => `  ${f.camelName}: ${buildFieldZod(f)},`).join("\n");
+
+  const createSchemaName = `create${model.pascalName}Schema`;
+  const updateSchemaName = `update${model.pascalName}Schema`;
+
+  const body = `${zodImport}
+
+const ${createSchemaName} = z.object({
+${createLines}
+});
+
+const ${updateSchemaName} = ${createSchemaName}.partial();
+`;
+
+  const footer = esm
+    ? `\nexport { ${createSchemaName}, ${updateSchemaName} };\n`
+    : `\nmodule.exports = { ${createSchemaName}, ${updateSchemaName} };\n`;
+
+  return body + footer;
+}
+
+module.exports = { generateEntityValidator };

package/src/generators/env.js

@@ -0,0 +1,123 @@
+"use strict";
+
+const { isEsm } = require("./syntax");
+
+/**
+ * Computes which env vars this project actually needs, based on the
+ * normalized config. Nothing here is generated for disabled features.
+ */
+function buildEnvSpec(config) {
+  const vars = [
+    { name: "NODE_ENV", zod: `z.enum(["development", "test", "production"]).default("development")`, example: "development" },
+    { name: "PORT", zod: `z.coerce.number().int().positive().default(3000)`, example: "3000" },
+    { name: "CORS_ORIGIN", zod: `z.string().default("*")`, example: "*" },
+  ];
+
+  if (config.database.type === "postgresql") {
+    vars.push({
+      name: "DATABASE_URL",
+      zod: `z.string().url()`,
+      example: "postgresql://user:password@localhost:5432/mydb",
+    });
+  }
+
+  if (config.database.type === "mongodb") {
+    vars.push({
+      name: "MONGODB_URI",
+      zod: `z.string().min(1)`,
+      example: "mongodb://localhost:27017/mydb",
+    });
+  }
+
+  if (config.redis) {
+    vars.push({
+      name: "REDIS_URL",
+      zod: `z.string().min(1).default("redis://localhost:6379")`,
+      example: "redis://localhost:6379",
+    });
+  }
+
+  // helpers/jwt.js always emits sign/verifyAccessToken (using JWT_SECRET/JWT_EXPIRES_IN) whenever
+  // it's generated at all — which happens for EITHER 'jwt' or 'refresh-token' — so these must be
+  // required in both cases, not just when 'jwt' itself is selected.
+  if (
+    config.authentication.enabled &&
+    (config.authentication.methods.includes("jwt") || config.authentication.methods.includes("refresh-token"))
+  ) {
+    vars.push({ name: "JWT_SECRET", zod: `z.string().min(10)`, example: "replace-with-a-long-random-secret" });
+    vars.push({ name: "JWT_EXPIRES_IN", zod: `z.string().default("15m")`, example: "15m" });
+  }
+
+  if (config.authentication.enabled && config.authentication.methods.includes("refresh-token")) {
+    vars.push({ name: "JWT_REFRESH_SECRET", zod: `z.string().min(10)`, example: "replace-with-a-long-random-secret" });
+    vars.push({ name: "JWT_REFRESH_EXPIRES_IN", zod: `z.string().default("7d")`, example: "7d" });
+  }
+
+  if (config.authentication.enabled && config.authentication.methods.includes("oauth")) {
+    vars.push({ name: "OAUTH_CLIENT_ID", zod: `z.string().min(1)`, example: "your-oauth-client-id" });
+    vars.push({ name: "OAUTH_CLIENT_SECRET", zod: `z.string().min(1)`, example: "your-oauth-client-secret" });
+    vars.push({ name: "OAUTH_CALLBACK_URL", zod: `z.string().url()`, example: "http://localhost:3000/auth/oauth/callback" });
+  }
+
+  return vars;
+}
+
+function generateValidateEnvFile(config) {
+  const vars = buildEnvSpec(config);
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+
+  const zodImport = esm ? `import { z } from "zod";` : `const { z } = require("zod");`;
+
+  const schemaFields = vars.map((v) => `    ${v.name}: ${v.zod},`).join("\n");
+
+  const fnBody = `${zodImport}
+
+const envSchema = z.object({
+${schemaFields}
+  });
+
+${isTs ? "export type Env = z.infer<typeof envSchema>;\n\n" : ""}function validateEnv(source${isTs ? ": NodeJS.ProcessEnv" : ""} = process.env)${isTs ? ": Env" : ""} {
+  const result = envSchema.safeParse(source);
+
+  if (!result.success) {
+    const messages = result.error.issues
+      .map((issue) => \`  \${issue.path.join(".")}: \${issue.message}\`)
+      .join("\\n");
+    throw new Error(\`Invalid environment configuration:\\n\${messages}\`);
+  }
+
+  return result.data;
+}
+
+${esm ? "export { validateEnv };" : "module.exports = { validateEnv };"}
+`;
+
+  return fnBody;
+}
+
+function generateEnvHelperFile(config, validateEnvImportPath) {
+  const esm = isEsm(config);
+  const dotenvImport = esm ? `import dotenv from "dotenv";` : `const dotenv = require("dotenv");`;
+  const validateImport = esm
+    ? `import { validateEnv } from "${validateEnvImportPath}";`
+    : `const { validateEnv } = require("${validateEnvImportPath}");`;
+
+  return `${dotenvImport}
+${validateImport}
+
+dotenv.config();
+
+const env = validateEnv(process.env);
+
+${esm ? "export { env };\nexport default env;" : "module.exports = { env };\nmodule.exports.default = env;"}
+`;
+}
+
+function buildEnvFileContents(config, { forExample }) {
+  const vars = buildEnvSpec(config);
+  const lines = vars.map((v) => `${v.name}=${forExample ? v.example : v.example}`);
+  return lines.join("\n") + "\n";
+}
+
+module.exports = { buildEnvSpec, generateValidateEnvFile, generateEnvHelperFile, buildEnvFileContents };

package/src/generators/errors.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const { isEsm } = require("./syntax");
+
+const NAMES = [
+  "HTTPException",
+  "BadRequestException",
+  "UnauthorizedException",
+  "ForbiddenException",
+  "NotFoundException",
+  "ConflictException",
+  "UnprocessableEntityException",
+  "InternalServerErrorException",
+];
+
+function generateErrorsFile(config) {
+  const isTs = config.language === "ts";
+  const esm = isEsm(config);
+  const kw = esm ? "export class" : "class";
+
+  const typedCtorArgs = isTs
+    ? {
+        base: "statusCode: number, message: string, details: unknown = null",
+        sub: "message = \"__DEFAULT__\", details: unknown = null",
+      }
+    : {
+        base: "statusCode, message, details = null",
+        sub: "message = \"__DEFAULT__\", details = null",
+      };
+
+  const fields = isTs ? "  public statusCode: number;\n  public details: unknown;\n\n" : "";
+
+  const base = `${kw} HTTPException extends Error {
+${fields}  constructor(${typedCtorArgs.base}) {
+    super(message);
+    this.name = "HTTPException";
+    this.statusCode = statusCode;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}`;
+
+  const subclasses = [
+    ["BadRequestException", 400, "Bad Request"],
+    ["UnauthorizedException", 401, "Unauthorized"],
+    ["ForbiddenException", 403, "Forbidden"],
+    ["NotFoundException", 404, "Not Found"],
+    ["ConflictException", 409, "Conflict"],
+    ["UnprocessableEntityException", 422, "Unprocessable Entity"],
+    ["InternalServerErrorException", 500, "Internal Server Error"],
+  ].map(([name, status, message]) => {
+    const ctorArgs = typedCtorArgs.sub.replace("__DEFAULT__", message);
+    return `${kw} ${name} extends HTTPException {
+  constructor(${ctorArgs}) {
+    super(${status}, message, details);
+    this.name = "${name}";
+  }
+}`;
+  });
+
+  const body = [base, ...subclasses].join("\n\n");
+  const footer = esm ? "" : `\n\nmodule.exports = {\n  ${NAMES.join(",\n  ")},\n};\n`;
+
+  return `${body}${footer}\n`;
+}
+
+module.exports = { generateErrorsFile };

package/src/generators/features/auth.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const { isEsm } = require("../syntax");
+const { sharedDir } = require("../paths");
+const { resolveImportPath } = require("../aliasResolver");
+
+/** helpers/bcrypt.{js,ts} — the only place password hashing logic lives. */
+function generateBcryptHelper(config) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const imports = esm ? `import bcrypt from "bcrypt";` : `const bcrypt = require("bcrypt");`;
+  const SALT_ROUNDS = 10;
+
+  const hashSig = isTs ? "hashPassword(password: string)" : "hashPassword(password)";
+  const compareSig = isTs
+    ? "comparePassword(password: string, hash: string)"
+    : "comparePassword(password, hash)";
+
+  return `${imports}
+
+const SALT_ROUNDS = ${SALT_ROUNDS};
+
+async function ${hashSig} {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+async function ${compareSig} {
+  return bcrypt.compare(password, hash);
+}
+
+${esm ? "export { hashPassword, comparePassword };" : "module.exports = { hashPassword, comparePassword };"}
+`;
+}
+
+/** helpers/jwt.{js,ts} — access/refresh token signing and verification, centralized. */
+function generateJwtHelper(config, aliasConfig) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const hasRefresh = config.authentication.methods.includes("refresh-token");
+  const fromDir = sharedDir(config, "helpers");
+  // helpers/env is a same-directory sibling of helpers/jwt, so this resolves to "./env" either way.
+  const envPath = resolveImportPath(config, aliasConfig, fromDir, `${fromDir}/env`);
+
+  const imports = isTs
+    ? `import jwt, { SignOptions } from "jsonwebtoken";`
+    : esm
+    ? `import jwt from "jsonwebtoken";`
+    : `const jwt = require("jsonwebtoken");`;
+  const envImport = esm ? `import { env } from "${envPath}";` : `const { env } = require("${envPath}");`;
+
+  const expiresInCast = isTs ? " as SignOptions[\"expiresIn\"]" : "";
+  const signAccessSig = isTs ? `signAccessToken(payload: object)` : "signAccessToken(payload)";
+  const verifyAccessSig = isTs ? "verifyAccessToken(token: string)" : "verifyAccessToken(token)";
+
+  let refreshFns = "";
+  if (hasRefresh) {
+    const signRefreshSig = isTs ? "signRefreshToken(payload: object)" : "signRefreshToken(payload)";
+    const verifyRefreshSig = isTs ? "verifyRefreshToken(token: string)" : "verifyRefreshToken(token)";
+    refreshFns = `
+function ${signRefreshSig} {
+  return jwt.sign(payload, env.JWT_REFRESH_SECRET, { expiresIn: env.JWT_REFRESH_EXPIRES_IN${expiresInCast} });
+}
+
+function ${verifyRefreshSig} {
+  return jwt.verify(token, env.JWT_REFRESH_SECRET);
+}
+`;
+  }
+
+  const exportsList = ["signAccessToken", "verifyAccessToken"];
+  if (hasRefresh) exportsList.push("signRefreshToken", "verifyRefreshToken");
+
+  return `${imports}
+${envImport}
+
+function ${signAccessSig} {
+  return jwt.sign(payload, env.JWT_SECRET, { expiresIn: env.JWT_EXPIRES_IN${expiresInCast} });
+}
+
+function ${verifyAccessSig} {
+  return jwt.verify(token, env.JWT_SECRET);
+}
+${refreshFns}
+${esm ? `export { ${exportsList.join(", ")} };` : `module.exports = { ${exportsList.join(", ")} };`}
+`;
+}
+
+/** middlewares/auth.{js,ts} — verifies the Bearer access token and attaches req.user. */
+function generateAuthMiddleware(config, aliasConfig) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const fromDir = sharedDir(config, "middlewares");
+  const jwtPath = resolveImportPath(config, aliasConfig, fromDir, `${sharedDir(config, "helpers")}/jwt`);
+  const errorsPath = resolveImportPath(config, aliasConfig, fromDir, `${sharedDir(config, "helpers")}/errors`);
+
+  const jwtImport = esm
+    ? `import { verifyAccessToken } from "${jwtPath}";`
+    : `const { verifyAccessToken } = require("${jwtPath}");`;
+  const errorsImport = esm
+    ? `import { UnauthorizedException } from "${errorsPath}";`
+    : `const { UnauthorizedException } = require("${errorsPath}");`;
+  const reqType = isTs ? `import { Request, Response, NextFunction } from "express";\n\n` : "";
+  const sig = isTs ? "(req: Request, res: Response, next: NextFunction)" : "(req, res, next)";
+
+  return `${reqType}${jwtImport}
+${errorsImport}
+
+function authenticate${sig} {
+  const header = req.headers.authorization;
+
+  if (!header || !header.startsWith("Bearer ")) {
+    return next(new UnauthorizedException("Missing or malformed Authorization header"));
+  }
+
+  const token = header.slice("Bearer ".length);
+
+  try {
+    req.user = verifyAccessToken(token);
+    return next();
+  } catch (error) {
+    return next(new UnauthorizedException("Invalid or expired token"));
+  }
+}
+
+${esm ? "export { authenticate };" : "module.exports = { authenticate };"}
+`;
+}
+
+/**
+ * helpers/oauth.stub.{js,ts} — GAZAN does NOT generate a working OAuth integration. "OAuth" isn't
+ * one thing — Google, GitHub, generic OIDC, etc. all need different scopes, callback handling, and
+ * token exchange, so wiring a specific provider is left to the project. This file exists so the
+ * gap is obvious and documented rather than a silently missing piece; see README's Authentication
+ * section for the same note.
+ */
+function generateOAuthStub(config) {
+  const esm = isEsm(config);
+  const isTs = config.language === "ts";
+  const sig = isTs ? "notConfigured(): never" : "notConfigured()";
+
+  return `/**
+ * OAuth is scaffolded as env vars only (OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET /
+ * OAUTH_CALLBACK_URL) — GAZAN does not generate a provider integration. To finish this:
+ *
+ *   1. Pick a provider (Google, GitHub, a generic OIDC server, ...).
+ *   2. Add its client library (e.g. \`openid-client\`, or a provider-specific SDK) yourself —
+ *      none is installed by default.
+ *   3. Implement the redirect + callback routes (e.g. GET /auth/oauth, GET /auth/oauth/callback)
+ *      using env.OAUTH_CLIENT_ID / env.OAUTH_CLIENT_SECRET / env.OAUTH_CALLBACK_URL below.
+ *   4. On success, mint your own access token the same way helpers/jwt.${isTs ? "ts" : "js"} does,
+ *      so the rest of the app (middlewares/auth) keeps working unchanged.
+ */
+function ${sig} {
+  throw new Error(
+    "OAuth is not implemented — this is a stub. See helpers/oauth.stub.${isTs ? "ts" : "js"} for what to build."
+  );
+}
+
+${esm ? "export { notConfigured };" : "module.exports = { notConfigured };"}
+`;
+}
+
+module.exports = { generateBcryptHelper, generateJwtHelper, generateAuthMiddleware, generateOAuthStub };