4bnode 4.1.0 → 4.1.1

package/skeleton/.4bnode/codegen.js

@@ -0,0 +1,1223 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// 4bnode shared code generation
+//
+// SINGLE SOURCE OF TRUTH for code that is emitted into generated projects.
+//
+// This module is PURE: no `fs`, no `path`, no npm dependencies, no I/O. Every
+// export takes plain values and returns strings. That purity is what lets the
+// same file run in two very different places:
+//
+//   1. The 4bnode CLI (add-*.js, index.js) — imports it from `./lib/codegen.js`.
+//   2. The in-project dashboard (.4bnode/dev-api.js) — imports a SYNCED COPY at
+//      `./codegen.js`, because it runs inside the user's project where the
+//      package's lib/ does not exist.
+//
+// The copy in skeleton/.4bnode/codegen.js is generated by `lib/sync-skeleton.js`
+// (npm run sync). Do NOT edit that copy by hand — edit THIS file and re-sync.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── Name helpers ────────────────────────────────────────────────────────────
+
+export function toCamelCase(str) {
+  return str.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+}
+
+export function toPascalCase(str) {
+  const camel = toCamelCase(str);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+export function sanitizeName(input) {
+  if (!input || typeof input !== "string") {
+    throw new Error("Name is required.");
+  }
+  const trimmed = input.trim();
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(trimmed)) {
+    throw new Error(
+      `Invalid name "${trimmed}". Use only letters, numbers, hyphens, and underscores. Must start with a letter.`
+    );
+  }
+  return trimmed;
+}
+
+// ── Pure string helpers for route files ─────────────────────────────────────
+// These operate on file CONTENT (a string) and return new content. The
+// file-reading/writing wrappers live in lib/routeFile.js (CLI) and inline in
+// dev-api.js (dashboard); both delegate here so the insertion logic is shared.
+
+export function addImportToContent(content, importStatement) {
+  const stmt = importStatement.trim();
+  if (content.includes(stmt)) return content;
+  return stmt + "\n" + content;
+}
+
+export function insertCodeIntoContent(content, codeBlock) {
+  const block = codeBlock.trim();
+
+  // Prefer inserting before "export default router;" — most reliable anchor.
+  const exportIndex = content.lastIndexOf("export default router;");
+  if (exportIndex !== -1) {
+    return (
+      content.slice(0, exportIndex) +
+      block +
+      "\n\n" +
+      content.slice(exportIndex)
+    );
+  }
+
+  // Fallback: before the last "});".
+  const lastClose = content.lastIndexOf("});");
+  if (lastClose !== -1) {
+    return content.slice(0, lastClose) + block + "\n" + content.slice(lastClose);
+  }
+
+  return content + "\n" + block + "\n";
+}
+
+// ── CRUD route builders ─────────────────────────────────────────────────────
+
+export function buildInsertCode(pascalName, fields, dataSource) {
+  const assignments = fields
+    .map((f) => `    ${f}: ${dataSource}.${f}`)
+    .join(",\n");
+
+  let passwordLogic = "";
+  if (fields.includes("password")) {
+    passwordLogic = `
+  if (newData.password) {
+    const salt = await bcrypt.genSalt(10);
+    newData.password = await bcrypt.hash(newData.password, salt);
+  }`;
+  }
+
+  return `
+router.post('/create', async (req, res) => {
+  const newData = {
+${assignments}
+  };
+${passwordLogic}
+  try {
+    const newDocument = new ${pascalName}(newData);
+    await newDocument.save();
+    res.json({ message: 'Data inserted successfully', data: newDocument });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});`;
+}
+
+export function buildReadCode(pascalName) {
+  return `
+router.get('/', async (req, res) => {
+  try {
+    const documents = await ${pascalName}.find();
+    res.json({ data: documents });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+router.get('/:id', async (req, res) => {
+  try {
+    const document = await ${pascalName}.findById(req.params.id);
+    if (!document) {
+      return res.status(404).json({ message: 'Document not found' });
+    }
+    res.json({ data: document });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});`;
+}
+
+export function buildUpdateCode(pascalName, fields, dataSource) {
+  const assignments = fields
+    .map((f) => `    ${f}: ${dataSource}.${f}`)
+    .join(",\n");
+
+  let passwordLogic = "";
+  if (fields.includes("password")) {
+    passwordLogic = `
+  if (updatedData.password) {
+    const salt = await bcrypt.genSalt(10);
+    updatedData.password = await bcrypt.hash(updatedData.password, salt);
+  }`;
+  }
+
+  return `
+router.put('/:id', async (req, res) => {
+  const updatedData = {
+${assignments}
+  };
+${passwordLogic}
+  try {
+    const updatedDocument = await ${pascalName}.findByIdAndUpdate(req.params.id, updatedData, { returnDocument: 'after' });
+    if (!updatedDocument) {
+      return res.status(404).json({ message: 'Document not found' });
+    }
+    res.json({ message: 'Data updated successfully', data: updatedDocument });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});`;
+}
+
+export function buildDeleteCode(pascalName) {
+  return `
+router.delete('/:id', async (req, res) => {
+  try {
+    const deletedDocument = await ${pascalName}.findByIdAndDelete(req.params.id);
+    if (!deletedDocument) {
+      return res.status(404).json({ message: 'Document not found' });
+    }
+    res.json({ message: 'Data deleted successfully', data: deletedDocument });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});`;
+}
+
+// ── Mongoose model generation ───────────────────────────────────────────────
+// Detailed generator supporting type, ref, required, unique, index, default,
+// and compound/text indexes. `pascalName` is used for both the schema variable
+// and the model name.
+
+export function generateMongooseModel(pascalName, fields, indexes = []) {
+  const fieldLines = fields.map((f) => {
+    const type = f.type || "String";
+    const parts = [
+      type === "ObjectId"
+        ? "type: mongoose.Schema.Types.ObjectId"
+        : `type: ${type}`,
+    ];
+    if (f.ref) parts.push(`ref: '${f.ref}'`);
+    if (f.required) parts.push("required: true");
+    if (f.unique) parts.push("unique: true");
+    if (f.index) parts.push("index: true");
+    if (f.default !== undefined && f.default !== "")
+      parts.push(`default: ${f.default}`);
+    return `  ${f.name}: { ${parts.join(", ")} }`;
+  });
+
+  let indexLines = "";
+  for (const idx of indexes) {
+    const fieldObj = idx.fields
+      .map((f) => {
+        if (f.direction === "text") return `${f.field}: 'text'`;
+        return `${f.field}: ${f.direction || 1}`;
+      })
+      .join(", ");
+    const options = idx.unique ? ", { unique: true }" : "";
+    indexLines += `\n${pascalName}Schema.index({ ${fieldObj} }${options});`;
+  }
+
+  return `import mongoose from 'mongoose';
+
+const ${pascalName}Schema = new mongoose.Schema({
+${fieldLines.join(",\n")}
+}, { timestamps: true });
+${indexLines}
+const ${pascalName} = mongoose.model('${pascalName}', ${pascalName}Schema);
+
+export default ${pascalName};
+`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1 — Security & Middleware
+//
+// File-content builders for generated middleware. Index.js wiring (imports +
+// app.use placement) is handled by the caller via `securityWiring()`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// src/middleware/errorHandler.js — central 404 + error handler.
+export function buildErrorHandlerFile() {
+  return `// Central error handling. Register AFTER all routes:
+//   app.use(notFound);
+//   app.use(errorHandler);
+export function notFound(req, res, next) {
+  res.status(404).json({ message: \`Not found - \${req.originalUrl}\` });
+}
+
+export function errorHandler(err, req, res, next) {
+  const status = err.status || err.statusCode || 500;
+  console.error(err);
+  res.status(status).json({
+    message: err.message || 'Server error',
+    ...(process.env.NODE_ENV === 'production' ? {} : { stack: err.stack }),
+  });
+}
+`;
+}
+
+// src/middleware/roles.js — role-based access control (RBAC).
+export function buildRolesGuardFile() {
+  return `// Role-based access control. Use AFTER the JWT auth middleware so req.user is set:
+//   router.get('/admin', auth, roles('admin'), handler);
+// Requires the login token payload to include a \`role\` (e.g. jwt.sign({ id, role })).
+const roles = (...allowed) => (req, res, next) => {
+  if (!req.user) {
+    return res.status(401).json({ message: 'Not authenticated' });
+  }
+  if (allowed.length && !allowed.includes(req.user.role)) {
+    return res.status(403).json({ message: 'Forbidden: insufficient role' });
+  }
+  next();
+};
+
+export default roles;
+`;
+}
+
+// src/middleware/apiKey.js — static API key auth via x-api-key header.
+export function buildApiKeyFile() {
+  return `// API key authentication. Named keys are managed by the 4bnode dashboard and
+// stored in src/api-keys.json. Send a key in the \`x-api-key\` request header:
+//   import apiKey from './src/middleware/apiKey.js';
+//   app.use('/api/private', apiKey);
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const KEYS_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'api-keys.json');
+let _cache = { mtimeMs: -1, keys: [] };
+
+// Read the keys file fresh when it changes (mtime-cached), so keys generated or
+// revoked in the dashboard take effect immediately — no restart needed.
+function loadKeys() {
+  try {
+    const { mtimeMs } = fs.statSync(KEYS_FILE);
+    if (mtimeMs !== _cache.mtimeMs) {
+      const list = JSON.parse(fs.readFileSync(KEYS_FILE, 'utf8'));
+      _cache = { mtimeMs, keys: (Array.isArray(list) ? list : []).map((k) => k && k.key).filter(Boolean) };
+    }
+  } catch {
+    _cache = { mtimeMs: -1, keys: [] };
+  }
+  return _cache.keys;
+}
+
+const apiKey = (req, res, next) => {
+  const provided = req.header('x-api-key');
+  const valid = loadKeys();
+  if (!provided || !valid.includes(provided)) {
+    return res.status(401).json({ message: 'Invalid or missing API key' });
+  }
+  next();
+};
+
+export default apiKey;
+`;
+}
+
+// src/middleware/validate.js — Zod request validation middleware.
+export function buildValidateFile() {
+  return `import { ZodError } from 'zod';
+
+// Validate part of the request against a Zod schema. Replaces req[source] with the
+// parsed/coerced data on success. Use as middleware:
+//   router.post('/', validate(userSchema), handler);          // validates req.body
+//   router.get('/', validate(querySchema, 'query'), handler); // validates req.query
+const validate = (schema, source = 'body') => (req, res, next) => {
+  const result = schema.safeParse(req[source]);
+  if (!result.success) {
+    const errors = (result.error instanceof ZodError ? result.error.issues : []).map((i) => ({
+      path: i.path.join('.'),
+      message: i.message,
+    }));
+    return res.status(400).json({ message: 'Validation failed', errors });
+  }
+  req[source] = result.data;
+  next();
+};
+
+export default validate;
+`;
+}
+
+// Map a Mongoose-style field descriptor to a Zod expression (no trailing optionality).
+function zodForField(field) {
+  const t = field.type || "String";
+  switch (t) {
+    case "Number":
+      return "z.coerce.number()";
+    case "Boolean":
+      return "z.coerce.boolean()";
+    case "Date":
+      return "z.coerce.date()";
+    case "ObjectId":
+      return "z.string().regex(/^[0-9a-fA-F]{24}$/, 'Invalid id')";
+    case "Array":
+      return "z.array(z.any())";
+    case "Buffer":
+    case "Mixed":
+      return "z.any()";
+    case "String":
+    default:
+      return "z.string()";
+  }
+}
+
+// src/validators/<name>.js — a Zod schema derived from a model's fields.
+export function buildZodSchemaFile(name, fields) {
+  const camel = toCamelCase(name);
+  const lines = fields.map((f) => {
+    let expr = zodForField(f);
+    if (!f.required) expr += ".optional()";
+    return `  ${f.name}: ${expr},`;
+  });
+  return `import { z } from 'zod';
+
+export const ${camel}Schema = z.object({
+${lines.join("\n")}
+});
+
+export default ${camel}Schema;
+`;
+}
+
+// Wire `validate(<model>Schema)` into the write endpoints of a route file, and add
+// the two needed imports. POST/PUT use the full schema; PATCH uses
+// `<schema>.partial()` so partial updates aren't forced to send every required
+// field. GET/DELETE are left alone (no body). Idempotent: skips endpoints that
+// already have a validate(...) middleware. `modelBase` is the validator file base
+// name (e.g. "user" → ../validators/user.js, userSchema). Returns the content
+// unchanged when there are no write endpoints to wire.
+export function wireValidateIntoRouteContent(content, modelBase) {
+  const schemaVar = toCamelCase(modelBase) + "Schema";
+  // Capture: (router.<method>('/...', <any existing middleware>, )(method)(handler arrow)
+  const handlerRe =
+    /(router\.(post|put|patch)\([^\n]*?,\s*)((?:async\s*)?\(\s*req\s*,\s*res\s*(?:,\s*next\s*)?\)\s*=>)/g;
+  let changed = false;
+  const replaced = content.replace(handlerRe, (full, head, method, handler) => {
+    if (head.includes("validate(")) return full; // already guarded
+    const expr = method === "patch" ? `${schemaVar}.partial()` : schemaVar;
+    changed = true;
+    return `${head}validate(${expr}), ${handler}`;
+  });
+  if (!changed) return content;
+  let out = addImportToContent(replaced, `import validate from '../middleware/validate.js';`);
+  out = addImportToContent(out, `import { ${schemaVar} } from '../validators/${modelBase}.js';`);
+  return out;
+}
+
+// Anchor comment that marks the central error handler in index.js. Route
+// registration looks for this so new routes are always inserted ABOVE it.
+export const ERROR_HANDLER_MARKER = "// ── Error handling (must be last) ──";
+
+// Index.js wiring plan for the selected app-level protections. Returns the imports
+// to add and the code blocks to insert before routes / before the listen call.
+// `features` is a set of: 'helmet', 'rateLimit', 'errorHandler'.
+export function securityWiring(features) {
+  const has = (f) => features.includes(f);
+  const imports = [];
+  const beforeRoutesParts = [];
+  let beforeListen = "";
+
+  if (has("helmet")) {
+    imports.push("import helmet from 'helmet';");
+    beforeRoutesParts.push("// ── Security headers ──\napp.use(helmet());");
+  }
+  if (has("rateLimit")) {
+    imports.push("import rateLimit from 'express-rate-limit';");
+    beforeRoutesParts.push(
+      `// ── Rate limiting ──
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,                 // limit each IP to 100 requests per window
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+app.use(apiLimiter);`
+    );
+  }
+  if (has("errorHandler")) {
+    imports.push(
+      "import { notFound, errorHandler } from './src/middleware/errorHandler.js';"
+    );
+    beforeListen = `${ERROR_HANDLER_MARKER}\napp.use(notFound);\napp.use(errorHandler);`;
+  }
+
+  return { imports, beforeRoutes: beforeRoutesParts.join("\n\n"), beforeListen };
+}
+
+// ── Pure index.js string transforms ─────────────────────────────────────────
+// Used by both the CLI (lib/indexFile.js) and the in-project dashboard
+// (dev-api.js) so the insertion logic lives in exactly one place.
+
+// Add an import line after the last existing import. Idempotent.
+export function addImportAfterLastImport(content, importLine) {
+  const line = importLine.trim();
+  if (content.includes(line)) return content;
+  const lines = content.split("\n");
+  let lastImportIdx = -1;
+  lines.forEach((l, i) => {
+    if (l.startsWith("import ")) lastImportIdx = i;
+  });
+  lines.splice(lastImportIdx + 1, 0, line);
+  return lines.join("\n");
+}
+
+// Insert a code block just before the server starts listening. If the central
+// error handler is present its marker takes precedence (new code stays above it,
+// the handler stays last). Otherwise anchor on the listen/start CALL — matched by
+// .index so the bare token inside `async function startServer(...)` is never hit.
+export function insertBeforeListenContent(content, codeBlock) {
+  const block = codeBlock.trim();
+  const markerIdx = content.indexOf(ERROR_HANDLER_MARKER);
+  let at;
+  if (markerIdx !== -1) {
+    at = markerIdx;
+  } else {
+    const m =
+      content.match(/(app|server)\.listen\(port/) || content.match(/^startServer\(/m);
+    if (!m) return content + "\n" + block + "\n";
+    at = m.index;
+  }
+  return content.slice(0, at) + block + "\n\n" + content.slice(at);
+}
+
+// Insert app-level middleware (e.g. helmet) ahead of the route/start section so it
+// wraps all subsequently-registered routes.
+export function insertBeforeRoutesContent(content, codeBlock) {
+  const block = codeBlock.trim();
+  const markers = ["// ── Start Server", "// ── Helpers", "\nstartServer("];
+  let idx = -1;
+  for (const marker of markers) {
+    idx = content.indexOf(marker);
+    if (idx !== -1) break;
+  }
+  if (idx === -1) {
+    const m = content.match(/^startServer\(/m);
+    idx = m ? m.index : content.length;
+  }
+  return content.slice(0, idx) + block + "\n\n" + content.slice(idx);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 2 — AI Builder
+//
+// The AI never emits raw code. It emits a structured PLAN (models + CRUD routes)
+// that these deterministic builders turn into files — so AI output is held to the
+// same shape and safety as hand-driven generation.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AI_FIELD_TYPES = [
+  "String", "Number", "Boolean", "Date", "ObjectId", "Array", "Mixed", "Buffer",
+];
+export const AI_OPERATIONS = ["create", "read", "update", "delete"];
+
+// Supported AI providers. Each plan is requested with a forced tool/function call
+// for structured output, so the same AI_PLAN_SCHEMA works across providers.
+export const AI_PROVIDERS = {
+  openai: {
+    id: "openai",
+    label: "OpenAI",
+    keyEnv: "OPENAI_API_KEY",
+    defaultModel: "gpt-4o-mini",
+    keyPlaceholder: "sk-...",
+    keysUrl: "platform.openai.com",
+  },
+  anthropic: {
+    id: "anthropic",
+    label: "Anthropic (Claude)",
+    keyEnv: "ANTHROPIC_API_KEY",
+    defaultModel: "claude-sonnet-4-6",
+    keyPlaceholder: "sk-ant-...",
+    keysUrl: "console.anthropic.com",
+  },
+};
+
+export const DEFAULT_AI_PROVIDER = "openai";
+
+// JSON Schema handed to Claude as a forced tool input — guarantees structured output.
+export const AI_PLAN_SCHEMA = {
+  type: "object",
+  properties: {
+    summary: { type: "string", description: "One sentence describing what will be built." },
+    models: {
+      type: "array",
+      description: "Mongoose models to create.",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Singular lowercase model name, e.g. 'post'." },
+          fields: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                name: { type: "string" },
+                type: { type: "string", enum: AI_FIELD_TYPES },
+                required: { type: "boolean" },
+                unique: { type: "boolean" },
+                ref: { type: "string", description: "Referenced model name (PascalCase) when type is ObjectId." },
+              },
+              required: ["name", "type"],
+            },
+          },
+        },
+        required: ["name", "fields"],
+      },
+    },
+    routes: {
+      type: "array",
+      description: "CRUD API routes to create, each bound to a model.",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Route name, usually plural, e.g. 'posts'." },
+          model: { type: "string", description: "The model name this route operates on." },
+          operations: { type: "array", items: { type: "string", enum: AI_OPERATIONS } },
+        },
+        required: ["name", "model", "operations"],
+      },
+    },
+  },
+  required: ["summary", "models", "routes"],
+};
+
+export const AI_SYSTEM_PROMPT = `You are a backend architect for a Node.js + Express + Mongoose application.
+Turn the user's request into a concrete plan of Mongoose models and CRUD API routes.
+Rules:
+- Respond ONLY by calling the emit_plan tool. Do not write prose or code.
+- Model names are singular and lowercase (e.g. "post", "user").
+- Route names are usually the plural of their model (e.g. "posts").
+- Allowed field types: ${AI_FIELD_TYPES.join(", ")}.
+- For relations between models, use type "ObjectId" with "ref" set to the related model's PascalCase name.
+- Include a "password" field (type String) only when authentication is clearly intended; it will be auto-hashed.
+- Every route must reference one of the models in the plan and choose from operations: ${AI_OPERATIONS.join(", ")}.
+- Keep the plan minimal and faithful to the request; do not invent unrelated models.`;
+
+// Coerce an arbitrary string into a safe JS identifier name, or null if impossible.
+function safeIdentifier(name) {
+  if (typeof name !== "string") return null;
+  const cleaned = name.trim().replace(/[^a-zA-Z0-9_-]/g, "");
+  if (!cleaned || !/^[a-zA-Z]/.test(cleaned)) return null;
+  return cleaned;
+}
+
+// Validate and clean a raw plan from the model into a safe, de-duplicated plan.
+// Defensive: bad models/fields/routes are dropped rather than trusted.
+export function normalizeAiPlan(plan) {
+  const out = {
+    summary: typeof plan?.summary === "string" ? plan.summary : "",
+    models: [],
+    routes: [],
+  };
+
+  const modelNames = new Set();
+  for (const m of Array.isArray(plan?.models) ? plan.models : []) {
+    const ident = safeIdentifier(m?.name);
+    if (!ident) continue;
+    const name = toCamelCase(ident);
+    if (modelNames.has(name)) continue;
+
+    const fields = [];
+    const seen = new Set();
+    for (const f of Array.isArray(m?.fields) ? m.fields : []) {
+      const fIdent = safeIdentifier(f?.name);
+      if (!fIdent || seen.has(fIdent)) continue;
+      const type = AI_FIELD_TYPES.includes(f?.type) ? f.type : "String";
+      const field = { name: fIdent, type };
+      if (f?.required) field.required = true;
+      if (f?.unique) field.unique = true;
+      const refIdent = type === "ObjectId" ? safeIdentifier(f?.ref) : null;
+      if (refIdent) field.ref = toPascalCase(refIdent);
+      seen.add(fIdent);
+      fields.push(field);
+    }
+    if (fields.length === 0) continue;
+    modelNames.add(name);
+    out.models.push({ name, fields });
+  }
+
+  // Map a model's lowercased name to its canonical name so a route that
+  // references the model with different capitalization still resolves to the
+  // exact file that was written. Without this, the model file (model.name) and
+  // the route import path (route.model) can diverge only in first-letter case —
+  // harmless on case-insensitive macOS, but a "Cannot find module" crash on a
+  // case-sensitive Linux production server.
+  const modelByKey = new Map(out.models.map((m) => [m.name.toLowerCase(), m.name]));
+
+  const routeNames = new Set();
+  for (const r of Array.isArray(plan?.routes) ? plan.routes : []) {
+    const ident = safeIdentifier(r?.name);
+    const model = safeIdentifier(r?.model);
+    if (!ident || !model) continue;
+    const name = toCamelCase(ident);
+    if (routeNames.has(name)) continue;
+    let operations = (Array.isArray(r?.operations) ? r.operations : []).filter((o) =>
+      AI_OPERATIONS.includes(o)
+    );
+    if (operations.length === 0) operations = [...AI_OPERATIONS];
+    routeNames.add(name);
+    const modelCamel = toCamelCase(model);
+    const resolvedModel = modelByKey.get(modelCamel.toLowerCase()) || modelCamel;
+    out.routes.push({ name, model: resolvedModel, operations });
+  }
+
+  return out;
+}
+
+// Build a complete CRUD route file (imports + router + selected operations + export)
+// for a model, reusing the same builders as `add crud`.
+export function buildCrudRouteFile(routeName, modelName, fieldNames = [], operations = AI_OPERATIONS) {
+  const pascal = toPascalCase(modelName);
+  const needsBcrypt =
+    fieldNames.includes("password") &&
+    (operations.includes("create") || operations.includes("update"));
+
+  const importLines = ["import express from 'express';"];
+  if (needsBcrypt) importLines.push("import bcrypt from 'bcrypt';");
+  importLines.push(`import ${pascal} from '../models/${modelName}.js';`);
+
+  const blocks = [];
+  if (operations.includes("create")) blocks.push(buildInsertCode(pascal, fieldNames, "req.body"));
+  if (operations.includes("read")) blocks.push(buildReadCode(pascal));
+  if (operations.includes("update")) blocks.push(buildUpdateCode(pascal, fieldNames, "req.body"));
+  if (operations.includes("delete")) blocks.push(buildDeleteCode(pascal));
+
+  return `${importLines.join("\n")}
+
+const router = express.Router();
+${blocks.join("\n")}
+
+export default router;
+`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dependency bookkeeping — record packages in package.json so the generated app
+// is always installable, even when a live `npm install` is interrupted/offline.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Known versions for packages 4bnode wires into generated apps.
+export const PACKAGE_VERSIONS = {
+  helmet: "^8.0.0",
+  "express-rate-limit": "^7.4.0",
+  zod: "^3.23.0",
+  bcrypt: "^5.1.1",
+  jsonwebtoken: "^9.0.2",
+  "socket.io": "^4.8.1",
+  ws: "^8.18.0",
+  serialport: "^12.0.0",
+  "@serialport/parser-readline": "^12.0.0",
+  mongoose: "^8.8.0",
+  multer: "^1.4.5-lts.1",
+};
+
+// Add packages to package.json (dependencies, or devDependencies when dev:true).
+// Pure: takes the file CONTENT, returns { content, changed }. Skips names already
+// present in either deps or devDeps. Unknown packages fall back to "latest".
+export function addDepsToPackageJson(content, names, { dev = false } = {}) {
+  const pkg = JSON.parse(content);
+  const key = dev ? "devDependencies" : "dependencies";
+  pkg[key] = pkg[key] || {};
+  let changed = false;
+  for (const name of names) {
+    const inDeps = pkg.dependencies && pkg.dependencies[name];
+    const inDev = pkg.devDependencies && pkg.devDependencies[name];
+    if (!inDeps && !inDev) {
+      pkg[key][name] = PACKAGE_VERSIONS[name] || "latest";
+      changed = true;
+    }
+  }
+  return { content: JSON.stringify(pkg, null, 2) + "\n", changed };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request-field detection — used by the API Tester to auto-fill keys from a route.
+// Handles BOTH destructuring (`const { a, b } = req.body`) AND direct member access
+// (`req.body.a`, `req.body['a']`), since generated CRUD routes use the latter.
+// ─────────────────────────────────────────────────────────────────────────────
+export function extractRequestFields(handlerBody, source = "body") {
+  const src = source === "query" ? "query" : "body";
+  const names = [];
+  const seen = new Set();
+  const add = (raw) => {
+    const n = (raw || "").trim();
+    if (n && /^[A-Za-z_$][\w$]*$/.test(n) && !seen.has(n)) {
+      seen.add(n);
+      names.push(n);
+    }
+  };
+  const body = handlerBody || "";
+  // const { a, b: x } = req.<src>  → take the key before any ':'
+  const destructure = body.match(new RegExp(`const\\s*\\{\\s*([^}]+)\\}\\s*=\\s*req\\.${src}`));
+  if (destructure) destructure[1].split(",").forEach((f) => add(f.split(":")[0]));
+  // req.<src>.field
+  const dot = new RegExp(`req\\.${src}\\.(\\w+)`, "g");
+  let m;
+  while ((m = dot.exec(body)) !== null) add(m[1]);
+  // req.<src>['field'] / req.<src>["field"]
+  const bracket = new RegExp(`req\\.${src}\\[\\s*['"](\\w+)['"]\\s*\\]`, "g");
+  while ((m = bracket.exec(body)) !== null) add(m[1]);
+  return names;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API Documentation — OpenAPI 3 spec + Swagger UI (served at /docs).
+// Reuses extractRequestFields output (endpoints) and model field metadata.
+// ─────────────────────────────────────────────────────────────────────────────
+function openApiType(t) {
+  switch (t) {
+    case "Number":
+    case "Int": return { type: "integer" };
+    case "Float": return { type: "number" };
+    case "Boolean": return { type: "boolean" };
+    case "Date":
+    case "DateTime": return { type: "string", format: "date-time" };
+    case "ObjectId": return { type: "string" };
+    case "Array": return { type: "array", items: {} };
+    case "Buffer": return { type: "string", format: "binary" };
+    case "Json":
+    case "Mixed": return { type: "object" };
+    case "String":
+    default: return { type: "string" };
+  }
+}
+
+// Build an OpenAPI 3.0 document from parsed endpoints + models.
+// endpoints: [{ method, path, fullPath, bodyFields[], queryFields[], params[], fileFields[], hasAuth }]
+// models: [{ name, fields:[{name,type,required}] }]
+export function buildOpenApiSpec({ title = "API", version = "1.0.0", endpoints = [], models = [] } = {}) {
+  const paths = {};
+  for (const ep of endpoints) {
+    const raw = ep.fullPath || ep.path || "/";
+    const oaPath = raw.replace(/:(\w+)/g, "{$1}");
+    const method = (ep.method || "GET").toLowerCase();
+    paths[oaPath] = paths[oaPath] || {};
+    const op = { summary: `${ep.method} ${raw}`, responses: { "200": { description: "Success" } } };
+
+    const parameters = [];
+    (ep.params || []).forEach((p) => parameters.push({ name: p, in: "path", required: true, schema: { type: "string" } }));
+    (ep.queryFields || []).forEach((f) => parameters.push({ name: f.name, in: "query", required: false, schema: openApiType(f.type) }));
+    if (parameters.length) op.parameters = parameters;
+
+    const bodyFields = ep.bodyFields || [];
+    const fileFields = ep.fileFields || [];
+    if (["post", "put", "patch"].includes(method) && (bodyFields.length || fileFields.length)) {
+      const properties = {};
+      const required = [];
+      bodyFields.forEach((f) => { properties[f.name] = openApiType(f.type); if (f.required) required.push(f.name); });
+      fileFields.forEach((f) => { properties[f.name] = { type: "string", format: "binary" }; });
+      const schema = { type: "object", properties };
+      if (required.length) schema.required = required;
+      const mime = fileFields.length ? "multipart/form-data" : "application/json";
+      op.requestBody = { content: { [mime]: { schema } } };
+    }
+    if (ep.hasAuth) op.security = [{ bearerAuth: [] }];
+    paths[oaPath][method] = op;
+  }
+
+  const schemas = {};
+  for (const m of models) {
+    const properties = {};
+    (m.fields || []).forEach((f) => { properties[f.name] = openApiType(f.type); });
+    schemas[toPascalCase(m.name)] = { type: "object", properties };
+  }
+
+  const components = { securitySchemes: { bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } };
+  if (Object.keys(schemas).length) components.schemas = schemas;
+
+  return { openapi: "3.0.0", info: { title, version }, servers: [{ url: "/" }], paths, components };
+}
+
+// A self-contained, modern API documentation page rendered from the spec.
+// No Swagger, no external CDN, no third-party branding — pure 4bnode dark style.
+// Two-pane layout: endpoint list on the left, selected endpoint details + an
+// inline "Try it" client on the right. Fetches the spec at runtime.
+export function buildDocsHtml(specUrl = "openapi.json") {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>API Documentation</title>
+<style>
+  * { box-sizing: border-box; }
+  :root {
+    --bg:#0f1117; --surface:#11141e; --card:#1a1d2b; --card-hover:#21253a; --input:#13161f;
+    --border:rgba(255,255,255,0.08); --text:#eceef4; --muted:#8b8fa3; --faint:#626880;
+    --accent:#0079ff; --accent-light:#3daefd; --accent-glow:rgba(0,121,255,0.14);
+  }
+  * { scrollbar-width: thin; }
+  html, body { margin:0; padding:0; height:100%; }
+  body { background:var(--bg); color:var(--text); line-height:1.5; height:100vh;
+    display:flex; flex-direction:column; overflow:hidden;
+    font-family:"Noto Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; }
+  .topbar { flex:none; display:flex; align-items:center; gap:14px;
+    background:var(--surface); border-bottom:1px solid var(--border); padding:14px 24px; }
+  .topbar h1 { font-size:17px; font-weight:700; margin:0;
+    background:linear-gradient(135deg,#3daefd,#0079ff); -webkit-background-clip:text;
+    background-clip:text; -webkit-text-fill-color:transparent; }
+  .pill-ver { font-size:12px; color:var(--accent-light); background:rgba(0,121,255,0.12);
+    border:1px solid rgba(0,121,255,0.25); padding:3px 9px; border-radius:999px; }
+  .layout { flex:1; display:flex; min-height:0; }
+  .sidebar { width:330px; flex:none; border-right:1px solid var(--border);
+    overflow-y:auto; padding:14px 12px; }
+  .search { width:100%; background:var(--input); border:1px solid var(--border);
+    color:var(--text); border-radius:9px; padding:8px 12px; font-size:13px; outline:none; margin-bottom:12px; }
+  .search:focus { border-color:var(--accent); }
+  .group-title { font-size:11px; font-weight:700; text-transform:uppercase; letter-spacing:0.6px;
+    color:var(--faint); margin:14px 6px 6px; }
+  .nav-item { display:flex; align-items:center; gap:9px; padding:8px 10px; border-radius:8px;
+    cursor:pointer; border:1px solid transparent; }
+  .nav-item:hover { background:var(--card-hover); }
+  .nav-item.active { background:var(--accent-glow); border-color:rgba(0,121,255,0.35); }
+  .nav-method { font-size:9.5px; font-weight:700; letter-spacing:0.4px; text-transform:uppercase;
+    color:#fff; padding:3px 0; border-radius:5px; width:46px; flex:none; text-align:center; }
+  .nav-path { font-family:ui-monospace,Menlo,monospace; font-size:12.5px; color:var(--text);
+    overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .main { flex:1; overflow-y:auto; padding:30px 40px; }
+  .main-empty { color:var(--faint); display:flex; height:100%; align-items:center; justify-content:center; }
+  .detail-head { display:flex; align-items:center; gap:14px; margin-bottom:6px; }
+  .method-lg { font-size:13px; font-weight:700; letter-spacing:0.5px; text-transform:uppercase;
+    color:#fff; padding:6px 12px; border-radius:8px; }
+  .path-lg { font-family:ui-monospace,Menlo,monospace; font-size:18px; color:var(--text); word-break:break-all; }
+  .detail-sum { color:var(--muted); margin:0 0 8px; }
+  .lock { color:var(--faint); font-size:12px; margin-left:8px; white-space:nowrap; }
+  .sec { font-size:11px; font-weight:700; text-transform:uppercase; letter-spacing:0.5px;
+    color:var(--faint); margin:22px 0 8px; }
+  .row { display:flex; gap:10px; align-items:center; padding:8px 0;
+    border-bottom:1px solid var(--border); font-size:13px; }
+  .row:last-child { border-bottom:none; }
+  .fname { font-family:ui-monospace,Menlo,monospace; color:var(--text); min-width:150px; }
+  .ftype { color:var(--accent-light); font-size:12px; }
+  .req { color:#ef4444; font-size:11px; font-weight:700; }
+  .opt { color:var(--faint); font-size:11px; }
+  .resp-code { font-family:ui-monospace,Menlo,monospace; color:#22c55e; font-weight:700; }
+  input.f, textarea.f { width:100%; max-width:540px; background:var(--input); border:1px solid var(--border);
+    color:var(--text); border-radius:8px; padding:8px 10px; font-size:13px; outline:none;
+    font-family:ui-monospace,Menlo,monospace; }
+  input.f:focus, textarea.f:focus { border-color:var(--accent); }
+  textarea.f { min-height:110px; resize:vertical; }
+  .try-field { margin-bottom:10px; }
+  .try-label { font-size:12px; color:var(--muted); margin-bottom:4px; display:block; }
+  .btn { background:var(--accent); color:#fff; border:none; border-radius:8px; padding:9px 18px;
+    font-size:13px; font-weight:600; cursor:pointer; }
+  .btn:hover { filter:brightness(1.08); }
+  .btn:disabled { opacity:.5; cursor:not-allowed; }
+  pre.out { background:#0a0c12; border:1px solid var(--border); border-radius:8px; padding:12px;
+    font-size:12.5px; color:#d5d8e3; overflow:auto; max-height:360px; max-width:540px; white-space:pre-wrap;
+    word-break:break-word; margin-top:10px; }
+  .out-status { font-family:ui-monospace,Menlo,monospace; font-size:12px; margin-top:10px; }
+  ::-webkit-scrollbar { width:9px; height:9px; }
+  ::-webkit-scrollbar-thumb { background:rgba(255,255,255,0.12); border-radius:6px; }
+</style>
+</head>
+<body>
+<div class="topbar">
+  <h1 id="apiTitle">API</h1>
+  <span class="pill-ver" id="apiVersion">v1.0.0</span>
+</div>
+<div class="layout">
+  <aside class="sidebar">
+    <input class="search" id="search" placeholder="Filter endpoints..." />
+    <div id="nav"></div>
+  </aside>
+  <main class="main" id="main"><div class="main-empty">Select an endpoint to view its details.</div></main>
+</div>
+<script>
+(function(){
+  var SPEC_URL='${specUrl}';
+  var COLORS={get:'#0079ff',post:'#22c55e',put:'#f59e0b',patch:'#a855f7',delete:'#ef4444',head:'#64748b',options:'#64748b'};
+  var uid=0; var ITEMS=[];
+  function esc(s){return String(s==null?'':s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+  function typeName(sc){if(!sc)return'';if(sc.format==='binary')return'file';if(sc.$ref)return sc.$ref.split('/').pop();return sc.type||'string';}
+  function paramsOf(op,where){return (op.parameters||[]).filter(function(p){return p.in===where;});}
+  function bodyOf(op){if(!op.requestBody)return null;var c=op.requestBody.content||{};var mime=Object.keys(c)[0];if(!mime)return null;return {mime:mime,schema:(c[mime]||{}).schema||{}};}
+  function sampleVal(sc){var t=typeName(sc);if(t==='integer'||t==='number')return 0;if(t==='boolean')return false;return'';}
+  function bodySkeleton(schema){var o={};var p=(schema&&schema.properties)||{};Object.keys(p).forEach(function(k){o[k]=sampleVal(p[k]);});return JSON.stringify(o,null,2);}
+  function groupKey(p){return (p.split('/').filter(Boolean)[0]||'general').replace(/[{}]/g,'');}
+  function collect(spec){var out=[];var paths=spec.paths||{};Object.keys(paths).forEach(function(p){var item=paths[p];Object.keys(item).forEach(function(m){out.push({path:p,method:m,op:item[m]});});});return out;}
+
+  function detailsHtml(e,id){
+    var html='';
+    var pp=paramsOf(e.op,'path'),qp=paramsOf(e.op,'query'),body=bodyOf(e.op);
+    if(pp.length||qp.length){
+      html+='<div class="sec">Parameters</div>';
+      pp.concat(qp).forEach(function(p){
+        html+='<div class="row"><span class="fname">'+esc(p.name)+'</span><span class="ftype">'+esc(typeName(p.schema)||'string')+' &middot; '+esc(p.in)+'</span>'+(p.required?'<span class="req">required</span>':'<span class="opt">optional</span>')+'</div>';
+      });
+    }
+    if(body){
+      html+='<div class="sec">Request body <span class="opt">('+esc(body.mime)+')</span></div>';
+      var props=(body.schema&&body.schema.properties)||{};var reqd=(body.schema&&body.schema.required)||[];
+      Object.keys(props).forEach(function(k){
+        html+='<div class="row"><span class="fname">'+esc(k)+'</span><span class="ftype">'+esc(typeName(props[k]))+'</span>'+(reqd.indexOf(k)>=0?'<span class="req">required</span>':'<span class="opt">optional</span>')+'</div>';
+      });
+    }
+    html+='<div class="sec">Responses</div>';
+    var resp=e.op.responses||{};
+    Object.keys(resp).forEach(function(code){
+      html+='<div class="row"><span class="resp-code">'+esc(code)+'</span><span class="detail-sum" style="margin:0">'+esc((resp[code]||{}).description||'')+'</span></div>';
+    });
+    html+='<div class="sec">Try it</div>';
+    html+='<div class="try-field"><label class="try-label">x-api-key</label><input class="f" id="'+id+'_apikey" placeholder="API key (saved for this browser)" /></div>';
+    pp.forEach(function(p){html+='<div class="try-field"><label class="try-label">'+esc(p.name)+' (path)</label><input class="f" data-kind="path" data-name="'+esc(p.name)+'" /></div>';});
+    qp.forEach(function(p){html+='<div class="try-field"><label class="try-label">'+esc(p.name)+' (query)</label><input class="f" data-kind="query" data-name="'+esc(p.name)+'" /></div>';});
+    if(e.op.security){html+='<div class="try-field"><label class="try-label">Authorization (Bearer token)</label><input class="f" id="'+id+'_auth" placeholder="token" /></div>';}
+    if(body){html+='<div class="try-field"><label class="try-label">Body (JSON)</label><textarea class="f" id="'+id+'_body">'+esc(bodySkeleton(body.schema))+'</textarea></div>';}
+    html+='<button class="btn" id="'+id+'_send">Send request</button>';
+    html+='<div class="out-status" id="'+id+'_status"></div>';
+    html+='<pre class="out" id="'+id+'_out" style="display:none"></pre>';
+    return html;
+  }
+
+  function wireTry(e,id,root){
+    var btn=root.querySelector('#'+id+'_send');if(!btn)return;
+    var keyEl=root.querySelector('#'+id+'_apikey');
+    if(keyEl){ try{ keyEl.value=localStorage.getItem('docs_api_key')||''; }catch(err){} }
+    // Auto-grow the body textarea to fit its content (capped, then scrolls).
+    var bodyTa=root.querySelector('#'+id+'_body');
+    if(bodyTa){
+      var autosize=function(){ bodyTa.style.height='auto'; bodyTa.style.height=Math.min(bodyTa.scrollHeight+2,600)+'px'; };
+      bodyTa.addEventListener('input',autosize);
+      autosize();
+    }
+    btn.addEventListener('click',function(){
+      var url=e.path;
+      root.querySelectorAll('[data-kind=path]').forEach(function(inp){url=url.replace('{'+inp.getAttribute('data-name')+'}',encodeURIComponent(inp.value||''));});
+      var qs=[];
+      root.querySelectorAll('[data-kind=query]').forEach(function(inp){if(inp.value)qs.push(encodeURIComponent(inp.getAttribute('data-name'))+'='+encodeURIComponent(inp.value));});
+      if(qs.length)url+=(url.indexOf('?')>=0?'&':'?')+qs.join('&');
+      var opts={method:e.method.toUpperCase(),headers:{}};
+      if(keyEl&&keyEl.value){ opts.headers['x-api-key']=keyEl.value; try{ localStorage.setItem('docs_api_key',keyEl.value); }catch(err){} }
+      var auth=root.querySelector('#'+id+'_auth');if(auth&&auth.value)opts.headers['Authorization']='Bearer '+auth.value;
+      var bodyEl=root.querySelector('#'+id+'_body');
+      if(bodyEl&&['post','put','patch'].indexOf(e.method)>=0){opts.headers['Content-Type']='application/json';opts.body=bodyEl.value;}
+      var statusEl=root.querySelector('#'+id+'_status');var outEl=root.querySelector('#'+id+'_out');
+      btn.disabled=true;statusEl.textContent='Sending...';var t0=Date.now();
+      fetch(url,opts).then(function(r){var ct=r.headers.get('content-type')||'';return r.text().then(function(txt){return {r:r,txt:txt,ct:ct};});}).then(function(d){
+        var color=d.r.ok?'#22c55e':'#ef4444';
+        statusEl.innerHTML='<span style="color:'+color+'">'+d.r.status+' '+esc(d.r.statusText)+'</span> &middot; '+(Date.now()-t0)+'ms';
+        var out=d.txt;if(d.ct.indexOf('application/json')>=0){try{out=JSON.stringify(JSON.parse(d.txt),null,2);}catch(err){}}
+        outEl.style.display='block';outEl.textContent=out;
+      }).catch(function(err){statusEl.innerHTML='<span style="color:#ef4444">Request failed</span>';outEl.style.display='block';outEl.textContent=String(err);}).then(function(){btn.disabled=false;});
+    });
+  }
+
+  function showDetail(e,navEl){
+    document.querySelectorAll('.nav-item').forEach(function(n){n.classList.remove('active');});
+    if(navEl)navEl.classList.add('active');
+    var id='ep'+(uid++);
+    var main=document.getElementById('main');
+    var color=COLORS[e.method]||'#64748b';
+    var lock=e.op.security?'<span class="lock">&#128274; requires auth</span>':'';
+    var html='<div class="detail-head"><span class="method-lg" style="background:'+color+'">'+esc(e.method)+'</span><span class="path-lg">'+esc(e.path)+'</span></div>';
+    html+='<div class="detail-sum">'+esc(e.op.summary||'')+lock+'</div>';
+    html+=detailsHtml(e,id);
+    main.innerHTML=html;main.scrollTop=0;
+    wireTry(e,id,main);
+  }
+
+  function render(spec){
+    document.getElementById('apiTitle').textContent=(spec.info&&spec.info.title)||'API';
+    document.getElementById('apiVersion').textContent='v'+((spec.info&&spec.info.version)||'1.0.0');
+    ITEMS=collect(spec);
+    var nav=document.getElementById('nav');nav.innerHTML='';
+    if(!ITEMS.length){nav.innerHTML='<div class="group-title">No endpoints</div>';return;}
+    var groups={};ITEMS.forEach(function(e){var k=groupKey(e.path);(groups[k]=groups[k]||[]).push(e);});
+    var first=null;
+    Object.keys(groups).sort().forEach(function(k){
+      var gt=document.createElement('div');gt.className='group-title';gt.textContent=k;nav.appendChild(gt);
+      groups[k].forEach(function(e){
+        var color=COLORS[e.method]||'#64748b';
+        var item=document.createElement('div');item.className='nav-item';
+        item.setAttribute('data-search',(e.method+' '+e.path+' '+(e.op.summary||'')).toLowerCase());
+        item.innerHTML='<span class="nav-method" style="background:'+color+'">'+esc(e.method)+'</span><span class="nav-path">'+esc(e.path)+'</span>';
+        item.addEventListener('click',function(){showDetail(e,item);});
+        nav.appendChild(item);
+        if(!first)first={e:e,item:item};
+      });
+    });
+    if(first)showDetail(first.e,first.item);
+  }
+
+  document.getElementById('search').addEventListener('input',function(ev){
+    var q=ev.target.value.toLowerCase();
+    document.querySelectorAll('.nav-item').forEach(function(c){c.style.display=c.getAttribute('data-search').indexOf(q)>=0?'':'none';});
+  });
+
+  fetch(SPEC_URL).then(function(r){return r.json();}).then(render).catch(function(){
+    document.getElementById('main').innerHTML='<div class="main-empty">Could not load the API spec.</div>';
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+
+// src/docs.js — a router that serves the spec + the self-contained docs page.
+// Password-only login page for protected docs (no username field). The
+// <!--ERR--> placeholder is swapped for an error message on a wrong password.
+export function buildDocsLoginHtml() {
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>API Documentation</title>
+<style>
+  *{box-sizing:border-box}
+  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#0f1117;color:#eceef4;font-family:"Noto Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}
+  form{background:#1a1d2b;border:1px solid rgba(255,255,255,0.08);border-radius:14px;padding:28px;width:340px;max-width:90vw;text-align:center}
+  h1{font-size:18px;margin:0 0 6px;background:linear-gradient(135deg,#3daefd,#0079ff);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}
+  p{color:#8b8fa3;font-size:13px;margin:0 0 18px}
+  input{width:100%;background:#13161f;border:1px solid rgba(255,255,255,0.08);border-radius:9px;color:#eceef4;padding:11px 13px;font-size:14px;outline:none}
+  input:focus{border-color:#0079ff}
+  .err{color:#ef4444;font-size:12px;min-height:16px;margin:8px 0 0}
+  button{width:100%;margin-top:14px;background:#0079ff;color:#fff;border:none;border-radius:9px;padding:11px;font-size:14px;font-weight:600;cursor:pointer}
+  button:hover{filter:brightness(1.08)}
+</style></head>
+<body>
+<form method="post" action="/docs/login">
+  <h1>API Documentation</h1>
+  <p>Enter the password to view the docs.</p>
+  <input type="password" name="password" placeholder="Password" autofocus autocomplete="current-password" />
+  <div class="err"><!--ERR--></div>
+  <button type="submit">Unlock</button>
+</form>
+</body></html>`;
+}
+
+export function buildDocsRouter() {
+  return `import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+
+const router = express.Router();
+const DIR = path.dirname(fileURLToPath(import.meta.url));
+const SPEC = path.join(DIR, 'openapi.json');
+const AUTH = path.join(DIR, 'docs-auth.json');
+
+// Optional password protection. If src/docs-auth.json holds a password hash, the
+// whole /docs surface requires a single password (NO username) via a small login
+// page + cookie. Set/remove the password from the dashboard (API Docs). Read live
+// (mtime-cached), so changes apply without a restart.
+let _authCache = { mtimeMs: -1, hash: null };
+function docsHash() {
+  try {
+    const { mtimeMs } = fs.statSync(AUTH);
+    if (mtimeMs !== _authCache.mtimeMs) {
+      const data = JSON.parse(fs.readFileSync(AUTH, 'utf8'));
+      _authCache = { mtimeMs, hash: (data && data.hash) || null };
+    }
+  } catch { _authCache = { mtimeMs: -1, hash: null }; }
+  return _authCache.hash;
+}
+function safeEq(a, b) {
+  try { const x = Buffer.from(String(a)), y = Buffer.from(String(b)); return x.length === y.length && crypto.timingSafeEqual(x, y); } catch { return false; }
+}
+function cookieToken(req) {
+  const m = (req.headers.cookie || '').match(/(?:^|; )docs_auth=([^;]+)/);
+  return m ? m[1] : null;
+}
+const LOGIN_HTML = ${JSON.stringify(buildDocsLoginHtml())};
+
+// Password submit — reachable without auth.
+router.post('/login', (req, res) => {
+  const expected = docsHash();
+  if (!expected) return res.redirect('/docs');
+  const got = crypto.createHash('sha256').update(String((req.body && req.body.password) || '')).digest('hex');
+  if (safeEq(got, expected)) {
+    res.setHeader('Set-Cookie', 'docs_auth=' + expected + '; Path=/docs; HttpOnly; SameSite=Lax; Max-Age=86400');
+    return res.redirect('/docs');
+  }
+  return res.status(401).type('html').send(LOGIN_HTML.replace('<!--ERR-->', 'Incorrect password'));
+});
+
+// Gate the rest of /docs behind the password (when one is set).
+router.use((req, res, next) => {
+  const expected = docsHash();
+  if (!expected) return next();                       // no password → open
+  if (safeEq(cookieToken(req), expected)) return next();
+  return res.status(401).type('html').send(LOGIN_HTML);
+});
+
+// Interactive API documentation. The page is fully self-contained (no external
+// CDN); the spec is generated by 4bnode and served from this app.
+router.get('/openapi.json', (req, res) => {
+  if (!fs.existsSync(SPEC)) return res.status(404).json({ error: 'API spec not generated yet.' });
+  res.sendFile(SPEC);
+});
+
+router.get('/', (req, res) => {
+  res.type('html').send(${JSON.stringify(buildDocsHtml("/docs/openapi.json"))});
+});
+
+export default router;
+`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Email (nodemailer) — SMTP with presets for popular providers (Brevo, etc.).
+// ─────────────────────────────────────────────────────────────────────────────
+export const MAIL_PROVIDERS = {
+  brevo:    { label: "Brevo",            host: "smtp-relay.brevo.com",    port: 587, secure: false, hint: "Login email + SMTP key (SMTP & API → SMTP)" },
+  sendgrid: { label: "SendGrid",         host: "smtp.sendgrid.net",       port: 587, secure: false, user: "apikey", hint: "User is literally 'apikey'; pass is your API key" },
+  mailgun:  { label: "Mailgun",          host: "smtp.mailgun.org",        port: 587, secure: false, hint: "Postmaster user + SMTP password" },
+  gmail:    { label: "Gmail",            host: "smtp.gmail.com",          port: 465, secure: true,  hint: "Use an App Password, not your login password" },
+  mailtrap: { label: "Mailtrap (test)",  host: "sandbox.smtp.mailtrap.io", port: 587, secure: false, hint: "Sandbox inbox for testing" },
+  smtp:     { label: "Custom SMTP",      host: "", port: 587, secure: false, hint: "Any SMTP server" },
+};
+
+// src/services/mailer.js — a configured nodemailer transport + sendMail helper + template.
+export function buildMailerService() {
+  return `import nodemailer from 'nodemailer';
+
+// Transport is configured from SMTP_* env vars (see .env). Works with Brevo,
+// SendGrid, Mailgun, Gmail, Mailtrap, or any SMTP server.
+const transporter = nodemailer.createTransport({
+  host: process.env.SMTP_HOST,
+  port: Number(process.env.SMTP_PORT) || 587,
+  secure: process.env.SMTP_SECURE === 'true', // true for port 465
+  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
+});
+
+// Wrap content in a simple, responsive HTML email.
+export function emailTemplate({ title = '', body = '' } = {}) {
+  return \`<!doctype html>
+<html>
+  <body style="margin:0;background:#f4f5f7;font-family:Arial,Helvetica,sans-serif;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="padding:24px 0;">
+      <tr><td align="center">
+        <table role="presentation" width="560" cellpadding="0" cellspacing="0" style="background:#fff;border-radius:10px;overflow:hidden;">
+          <tr><td style="background:#0079ff;padding:18px 28px;color:#fff;font-size:18px;font-weight:bold;">\${title}</td></tr>
+          <tr><td style="padding:28px;color:#333;font-size:15px;line-height:1.6;">\${body}</td></tr>
+          <tr><td style="padding:16px 28px;color:#9aa0ab;font-size:12px;border-top:1px solid #eee;">Sent by your app</td></tr>
+        </table>
+      </td></tr>
+    </table>
+  </body>
+</html>\`;
+}
+
+// Send an email. Pass html or text (or use emailTemplate for html).
+export async function sendMail({ to, subject, html, text, from } = {}) {
+  if (!to || !subject) throw new Error('sendMail requires { to, subject }');
+  return transporter.sendMail({
+    from: from || process.env.SMTP_FROM || process.env.SMTP_USER,
+    to,
+    subject,
+    text,
+    html,
+  });
+}
+
+// Verify the SMTP connection/credentials.
+export function verifyMailer() {
+  return transporter.verify();
+}
+
+export default { sendMail, emailTemplate, verifyMailer, transporter };
+`;
+}
+