db-model-router 1.0.5 → 1.0.7

package/src/cli/generate-openapi.js

@@ -5,6 +5,13 @@ function generateOpenAPISpec(models, options = {}) {
   const basePath = options.basePath || "/api";
   const title = options.title || "REST Router API";
   const version = options.version || "1.0.0";
+  const relationships = options.relationships || [];
+
+  // Build a lookup: child table -> { parent, foreignKey }
+  const childMap = {};
+  for (const rel of relationships) {
+    childMap[rel.child] = { parent: rel.parent, foreignKey: rel.foreignKey };
+  }
 
   const spec = {
     openapi: "3.0.3",
@@ -39,14 +46,34 @@ function generateOpenAPISpec(models, options = {}) {
     };
 
     const ref = { $ref: `#/components/schemas/${schemaName}` };
-    const prefix = `${basePath}/${m.table}`;
+
+    // Determine path prefix: nested under parent if this is a child table
+    let prefix;
+    const isChild = !!childMap[m.table];
+    let fkParam = null;
+    if (isChild) {
+      const { parent, foreignKey } = childMap[m.table];
+      prefix = `${basePath}/${parent}/{${foreignKey}}/${m.table}`;
+      fkParam = {
+        name: foreignKey,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+        description: `${capitalize(parent)} foreign key`,
+      };
+    } else {
+      prefix = `${basePath}/${m.table}`;
+    }
+
+    // Helper: prepend FK path param for child routes
+    const withFk = (params) => (fkParam ? [fkParam, ...params] : params);
 
     // GET / — list
     spec.paths[`${prefix}/`] = {
       get: {
         tags: [tag],
         summary: `List ${m.table}`,
-        parameters: [
+        parameters: withFk([
           {
             name: "page",
             in: "query",
@@ -69,7 +96,7 @@ function generateOpenAPISpec(models, options = {}) {
             in: "query",
             schema: { type: "string", enum: ["json", "csv", "xml"] },
           },
-        ],
+        ]),
         responses: {
           200: {
             description: "Success",
@@ -141,7 +168,7 @@ function generateOpenAPISpec(models, options = {}) {
       get: {
         tags: [tag],
         summary: `Get ${m.table} by ${pk}`,
-        parameters: [
+        parameters: withFk([
           { name: pk, in: "path", required: true, schema: { type: "string" } },
           { name: "select_columns", in: "query", schema: { type: "string" } },
           {
@@ -149,7 +176,7 @@ function generateOpenAPISpec(models, options = {}) {
             in: "query",
             schema: { type: "string", enum: ["json", "csv", "xml"] },
           },
-        ],
+        ]),
         responses: {
           200: {
             description: "Success",
@@ -161,9 +188,9 @@ function generateOpenAPISpec(models, options = {}) {
       post: {
         tags: [tag],
         summary: `Insert a ${m.table}`,
-        parameters: [
+        parameters: withFk([
           { name: pk, in: "path", required: true, schema: { type: "string" } },
-        ],
+        ]),
         requestBody: { content: { "application/json": { schema: ref } } },
         responses: {
           200: {
@@ -175,9 +202,9 @@ function generateOpenAPISpec(models, options = {}) {
       put: {
         tags: [tag],
         summary: `Update a ${m.table}`,
-        parameters: [
+        parameters: withFk([
           { name: pk, in: "path", required: true, schema: { type: "string" } },
-        ],
+        ]),
         requestBody: { content: { "application/json": { schema: ref } } },
         responses: {
           200: {
@@ -190,9 +217,9 @@ function generateOpenAPISpec(models, options = {}) {
       patch: {
         tags: [tag],
         summary: `Partial update a ${m.table}`,
-        parameters: [
+        parameters: withFk([
           { name: pk, in: "path", required: true, schema: { type: "string" } },
-        ],
+        ]),
         requestBody: {
           content: { "application/json": { schema: { type: "object" } } },
         },
@@ -207,9 +234,9 @@ function generateOpenAPISpec(models, options = {}) {
       delete: {
         tags: [tag],
         summary: `Delete a ${m.table}`,
-        parameters: [
+        parameters: withFk([
           { name: pk, in: "path", required: true, schema: { type: "string" } },
-        ],
+        ]),
         responses: {
           200: { description: "Deleted" },
           404: { description: "Not Found" },

package/src/cli/generate-route.js

@@ -26,17 +26,63 @@ function safeVarName(name) {
 function generateRouteFile(tableName, modelsRelPath) {
   const varName = safeVarName(tableName);
   return `import dbModelRouter from "db-model-router";
-import ${varName} from "${modelsRelPath}/${tableName}.js";
+import express from "express";
+import { ${varName} } from "#models";
 
+const router = express.Router({ mergeParams: true });
 const { route } = dbModelRouter;
 
-export default route(${varName});
+router.use("/", route(${varName}));
+
+export default router;
 `;
 }
 
+/**
+ * Generate a parent route file that includes its own CRUD and mounts child routes.
+ * e.g., routes/orders/index.js mounts order_items under /:order_id/items
+ *
+ * @param {string} tableName - Parent table name
+ * @param {Array<{child, foreignKey}>} children - Child relationships for this parent
+ * @returns {string}
+ */
+function generateParentRouteFile(tableName, children) {
+  const varName = safeVarName(tableName);
+  let code = `import dbModelRouter from "db-model-router";
+import express from "express";
+import { ${varName} } from "#models";
+`;
+
+  // Import child routes
+  for (const child of children) {
+    const childVar = safeVarName(child.child);
+    code += `import ${childVar}Route from "./${child.child}/index.js";\n`;
+  }
+
+  code += `
+const router = express.Router({ mergeParams: true });
+const { route } = dbModelRouter;
+
+`;
+
+  // Mount child routes BEFORE own CRUD to prevent path clashing
+  for (const child of children) {
+    const childVar = safeVarName(child.child);
+    code += `router.use("/:${child.foreignKey}/${child.child}", ${childVar}Route);\n`;
+  }
+
+  code += `
+// CRUD routes for ${tableName}
+router.use("/", route(${varName}));
+
+export default router;
+`;
+  return code;
+}
+
 /**
  * Generate a child route file that scopes queries by parent FK.
- * e.g., posts/:post_id/comments — filters comments where post_id = :post_id
+ * e.g., routes/orders/items/index.js — filters items where order_id = :order_id
  */
 function generateChildRouteFile(
   childTable,
@@ -46,12 +92,16 @@ function generateChildRouteFile(
 ) {
   const varName = safeVarName(childTable);
   return `import dbModelRouter from "db-model-router";
-import ${varName} from "${modelsRelPath}/${childTable}.js";
+import express from "express";
+import { ${varName} } from "#models";
 
+const router = express.Router({ mergeParams: true });
 const { route } = dbModelRouter;
 
 // Child route: scoped by parent ${parentTable} via ${fkColumn}
-export default route(${varName}, { ${fkColumn}: "params.${fkColumn}" });
+router.use("/", route(${varName}, { ${fkColumn}: "params.${fkColumn}" }));
+
+export default router;
 `;
 }
 
@@ -67,7 +117,7 @@ export default route(${varName}, { ${fkColumn}: "params.${fkColumn}" });
  * @param {{ includeDocs?: boolean }} [options]
  */
 function generateRoutesIndexFile(tableNames, relationships = [], options = {}) {
-  let imports = `import express from "express";\n\nconst router = express.Router();\n\n`;
+  let imports = `import express from "express";\n\nconst router = express.Router({ mergeParams: true });\n\n`;
 
   // Collect child tables that are nested under parents
   const nestedChildren = new Set();
@@ -75,17 +125,11 @@ function generateRoutesIndexFile(tableNames, relationships = [], options = {}) {
     nestedChildren.add(rel.child);
   }
 
-  // Import top-level routes only (not children)
+  // Import top-level routes only (children are mounted inside parent folders)
   for (const table of tableNames) {
     if (nestedChildren.has(table)) continue;
     const varName = safeVarName(table);
-    imports += `import ${varName}Route from "./${table}.js";\n`;
-  }
-
-  // Import child routes from subfolders
-  for (const rel of relationships) {
-    const varName = safeVarName(rel.child);
-    imports += `import ${varName}ChildRoute from "./${rel.parent}/${rel.child}.js";\n`;
+    imports += `import ${varName}Route from "./${table}/index.js";\n`;
   }
 
   // Import docs route if openapi is generated
@@ -100,19 +144,13 @@ function generateRoutesIndexFile(tableNames, relationships = [], options = {}) {
     imports += `router.use("/docs", docsRoute);\n`;
   }
 
-  // Mount top-level routes
+  // Mount top-level routes (children are already mounted inside their parent's index.js)
   for (const table of tableNames) {
     if (nestedChildren.has(table)) continue;
     const varName = safeVarName(table);
     imports += `router.use("/${table}", ${varName}Route);\n`;
   }
 
-  // Mount child routes under parent path
-  for (const rel of relationships) {
-    const childVar = safeVarName(rel.child);
-    imports += `router.use("/${rel.parent}/:${rel.foreignKey}/${rel.child}", ${childVar}ChildRoute);\n`;
-  }
-
   imports += "\nexport default router;\n";
   return imports;
 }
@@ -472,7 +510,7 @@ async function main() {
       }
     }
     if (modelMeta.length > 0) {
-      const spec = generateOpenAPISpec(modelMeta);
+      const spec = generateOpenAPISpec(modelMeta, { relationships });
       const specPath = path.join(routesDir, "openapi.json");
       fs.writeFileSync(specPath, JSON.stringify(spec, null, 2));
       console.log(`  Created ${specPath}`);
@@ -606,6 +644,7 @@ if (require.main === module) {
 
 module.exports = {
   generateRouteFile,
+  generateParentRouteFile,
   generateChildRouteFile,
   generateRoutesIndexFile,
   generateTestFile,

package/src/cli/generate-saas-structure.js

@@ -0,0 +1,122 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { generateSaasMigrations } = require("./saas/generate-saas-migrations");
+const { generateSaasModels } = require("./saas/generate-saas-models");
+const {
+  generateAuthenticateMiddleware,
+  generateTenantIsolationMiddleware,
+  generateHasPermissionMiddleware,
+} = require("./saas/generate-saas-middleware");
+const {
+  generateCrudRoutes,
+  generateAuthRoutes,
+  generateRoutesIndex,
+} = require("./saas/generate-saas-routes");
+const { generateSaasSeeds } = require("./saas/generate-saas-seeds");
+const {
+  generatePasswordUtil,
+  generateModulesUtil,
+  generateWebhookUtil,
+} = require("./saas/generate-saas-utils");
+
+/**
+ * Read the existing .gitignore file and append `credentials.md` if not already present.
+ * Returns the full .gitignore content to be written.
+ *
+ * @returns {string} Updated .gitignore content
+ */
+function getGitignoreContent() {
+  const gitignorePath = path.join(process.cwd(), ".gitignore");
+  let content = "";
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, "utf8");
+  }
+  if (!content.includes("credentials.md")) {
+    content = content.trimEnd() + "\ncredentials.md\n";
+  }
+  return content;
+}
+
+/**
+ * Main SaaS structure generator orchestrator.
+ *
+ * Calls all sub-generators and aggregates their output into a single
+ * planned[] array of { relPath, content } objects compatible with the
+ * existing generate command's file write loop.
+ *
+ * @param {string} adapter - Database adapter name (e.g. "postgres", "mysql", "sqlite3")
+ * @param {object} [options] - Generation options
+ * @param {boolean} [options.dryRun] - If true, files will not be written (handled by caller)
+ * @param {boolean} [options.json] - If true, output JSON format (handled by caller)
+ * @param {Date|number} [options.timestamp] - Base timestamp for migration files
+ * @param {string[]} [options.tableNames] - Schema-generated table names for routes index
+ * @param {Array<{parent, child, foreignKey}>} [options.relationships] - Schema relationships for routes index
+ * @param {{ includeDocs?: boolean }} [options.routeOptions] - Options for routes index generation
+ * @returns {Array<{ relPath: string, content: string }>} Combined planned file array
+ */
+function generateSaasStructure(adapter, options) {
+  const opts = options || {};
+  const planned = [];
+
+  // 1. Migrations
+  const timestamp = opts.timestamp || new Date();
+  const migrations = generateSaasMigrations(adapter, timestamp);
+  for (const entry of migrations) {
+    planned.push(entry);
+  }
+
+  // 2. Models (includes models/index.js barrel with both SaaS + dbmr tables)
+  const models = generateSaasModels(adapter, opts.tableNames || []);
+  for (const entry of models) {
+    planned.push(entry);
+  }
+
+  // 3. Middleware
+  planned.push(generateAuthenticateMiddleware());
+  planned.push(generateTenantIsolationMiddleware());
+  planned.push(generateHasPermissionMiddleware());
+
+  // 4. Routes (CRUD + auth + combined index with dbmr routes)
+  const crudRoutes = generateCrudRoutes();
+  for (const entry of crudRoutes) {
+    planned.push(entry);
+  }
+  planned.push(generateAuthRoutes());
+  planned.push(
+    generateRoutesIndex(
+      opts.tableNames || [],
+      opts.relationships || [],
+      opts.routeOptions || {},
+    ),
+  );
+
+  // 5. Seeds
+  const seeds = generateSaasSeeds(adapter);
+  for (const entry of seeds) {
+    planned.push(entry);
+  }
+
+  // 6. Utilities
+  planned.push({
+    relPath: "commons/password.js",
+    content: generatePasswordUtil(),
+  });
+  planned.push({
+    relPath: "commons/modules.js",
+    content: generateModulesUtil(),
+  });
+  planned.push({
+    relPath: "commons/webhook.js",
+    content: generateWebhookUtil(),
+  });
+
+  // 7. .gitignore update (add credentials.md)
+  planned.push({ relPath: ".gitignore", content: getGitignoreContent() });
+
+  return planned;
+}
+
+module.exports = { generateSaasStructure, getGitignoreContent };

package/src/cli/init/generators.js

@@ -169,6 +169,7 @@ function buildEnvContent(answers, mode, secrets) {
   const lines = [];
   lines.push("# Server");
   lines.push("PORT=3000");
+  lines.push("API_BASE_PATH=/api");
   lines.push("");
   lines.push("# Database");
 
@@ -367,21 +368,21 @@ function generateAppJs(answers) {
     answers.framework === "ultimate-express" ? "ultimate-express" : "express";
 
   // Imports
-  let imports = `const express = require("${frameworkPkg}");
-const { init, db } = require("db-model-router");
-const session = require("express-session");`;
+  let imports = `import express from "${frameworkPkg}";
+import { init, db } from "db-model-router";
+import session from "express-session";`;
 
   if (answers.session === "redis") {
-    imports += `\nconst RedisStore = require("connect-redis").default;
-const { Redis } = require("ioredis");`;
+    imports += `\nimport RedisStore from "connect-redis";
+import { Redis } from "ioredis";`;
   }
   if (answers.rateLimiting) {
-    imports += `\nconst rateLimit = require("express-rate-limit");`;
+    imports += `\nimport rateLimit from "express-rate-limit";`;
   }
   if (answers.helmet) {
-    imports += `\nconst helmet = require("helmet");`;
+    imports += `\nimport helmet from "helmet";`;
   }
-  imports += `\nconst logger = require("./middleware/logger");`;
+  imports += `\nimport logger from "./middleware/logger.js";`;
 
   // Rate limiting block
   const rateLimitBlock = answers.rateLimiting
@@ -396,9 +397,7 @@ const { Redis } = require("ioredis");`;
   const helmetBlock = answers.helmet ? `app.use(helmet());` : "";
 
   return `${imports}
-
-// Load environment variables
-require("dotenv").config();
+import "dotenv/config";
 
 // Initialize database adapter
 init("${answers.database}");
@@ -413,6 +412,10 @@ app.use(express.urlencoded({ extended: true }));
 ${helmetBlock ? helmetBlock + "\n" : ""}${rateLimitBlock ? rateLimitBlock + "\n" : ""}${sessionBlock(answers)}
 app.use(logger);
 
+// Routes
+import routes from "#routes/index.js";
+app.use(process.env.API_BASE_PATH || "/api", routes);
+
 // Health check
 app.get("/health", (req, res) => {
   res.json({ status: "ok", timestamp: new Date().toISOString() });
@@ -428,7 +431,7 @@ app.listen(PORT, () => {
   console.log(\`Server running on port \${PORT}\`);
 });
 
-module.exports = app;
+export default app;
 `;
 }
 
@@ -551,14 +554,15 @@ function generateMigrateScript(answers) {
 
   if (isNoSql) {
     return `#!/usr/bin/env node
-"use strict";
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { fileURLToPath } from "url";
+import "dotenv/config";
 
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-require("dotenv").config();
+import { init, db } from "db-model-router";
 
-const { init, db } = require("db-model-router");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 init("${answers.database}");
 
@@ -598,7 +602,7 @@ async function migrate() {
     const content = fs.readFileSync(filePath, "utf8");
     const checksum = crypto.createHash("md5").update(content).digest("hex");
 
-    const migration = require(filePath);
+    const migration = await import(filePath);
     console.log(\`  Running migration: \${file}\`);
     await migration.up(db);
     await recordMigration(file, checksum);
@@ -622,14 +626,15 @@ migrate().catch(err => {
   }
 
   return `#!/usr/bin/env node
-"use strict";
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { fileURLToPath } from "url";
+import "dotenv/config";
 
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-require("dotenv").config();
+import { init, db } from "db-model-router";
 
-const { init, db } = require("db-model-router");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 init("${answers.database}");
 
@@ -700,14 +705,15 @@ function generateAddMigrationScript(answers) {
   const isNoSql = NOSQL_DATABASES.includes(answers.database);
   const ext = isNoSql ? "js" : "sql";
   const template = isNoSql
-    ? `"use strict";\\n\\nmodule.exports = {\\n  async up(db) {\\n    // Write your migration here\\n  },\\n\\n  async down(db) {\\n    // Write your rollback here\\n  },\\n};\\n`
+    ? `export async function up(db) {\\n  // Write your migration here\\n}\\n\\nexport async function down(db) {\\n  // Write your rollback here\\n}\\n`
     : `-- Write your migration SQL here\\n`;
 
   return `#!/usr/bin/env node
-"use strict";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
 
-const fs = require("fs");
-const path = require("path");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const migrationsDir = path.join(__dirname, "migrations");
 
@@ -1422,6 +1428,8 @@ if (isMain) {
   const pkg = await import("db-model-router");
   const mod = pkg.default || pkg;
   mod.init("${answers.database}");
+  mod.db.connect({
+  ${dbConnectArgs(answers.database)}});
   const migrationsDir = path.join(__dirname, "${migrationsRel}");
   runMigrations(mod.db, migrationsDir)
     .then(() => process.exit(0))
@@ -1490,6 +1498,8 @@ if (isMain) {
   const pkg = await import("db-model-router");
   const mod = pkg.default || pkg;
   mod.init("${answers.database}");
+  mod.db.connect({
+  ${dbConnectArgs(answers.database)}});
   const migrationsDir = path.join(__dirname, "${migrationsRel}");
   runMigrations(mod.db, migrationsDir)
     .then(() => process.exit(0))
@@ -1726,7 +1736,9 @@ import configureSession from "${commonsPrefix}/session.js";
 import applySecurity from "${commonsPrefix}/security.js";
 import logger from "${middlewarePrefix}/logger.js";
 import route from "${routePrefix}/index.js";
-
+import { fileURLToPath } from 'node:url';
+import path from "path";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const app = express();
 const PORT = process.env.PORT || 3000;
 

package/src/cli/init.js

@@ -254,6 +254,14 @@ function updatePackageJson(answers, outputDir) {
   const scripts = getScripts(outputDir);
 
   pkg.type = "module";
+  pkg.imports = {
+    "#root/*.js": "./*.js",
+    "#models": "./models/index.js",
+    "#models/*.js": "./models/*.js",
+    "#routes/*.js": "./routes/*.js",
+    "#commons/*.js": "./commons/*.js",
+    "#middleware/*.js": "./middleware/*.js",
+  };
   pkg.scripts = Object.assign({}, pkg.scripts || {}, scripts);
   pkg.dependencies = Object.assign({}, pkg.dependencies || {}, dependencies);
   pkg.devDependencies = Object.assign(

package/src/cli/main.js

@@ -9,6 +9,7 @@ const generateCmd = require("./commands/generate");
 const doctorCmd = require("./commands/doctor");
 const diffCmd = require("./commands/diff");
 const helpCmd = require("./commands/help");
+const dbManagerCmd = require("./commands/db-manager");
 
 /**
  * Map of subcommand names to their handler functions.
@@ -19,6 +20,7 @@ const COMMANDS = {
   generate: generateCmd,
   doctor: doctorCmd,
   diff: diffCmd,
+  "db-manager": dbManagerCmd,
   help: helpCmd,
 };
 
@@ -31,6 +33,7 @@ const COMMAND_DESCRIPTIONS = {
   generate: "Generate models, routes, tests, and OpenAPI spec from a schema",
   doctor: "Validate schema, check dependencies, and verify file sync",
   diff: "Preview changes between current files and what the schema would produce",
+  "db-manager": "Start a live database management UI",
   help: "Show help for a command",
 };
 
@@ -64,10 +67,14 @@ const COMMAND_FLAGS = {
     ["--routes", "Generate only route files"],
     ["--openapi", "Generate only OpenAPI spec"],
     ["--tests", "Generate only test files"],
-    ["--llm-docs", "Generate only LLM documentation"],
+    ["--db-manager", "Generate DB Manager UI (SQL adapters only)"],
   ],
   doctor: [["--from <path>", "Schema file (default: dbmr.schema.json)"]],
   diff: [["--from <path>", "Schema file (default: dbmr.schema.json)"]],
+  "db-manager": [
+    ["--env <path>", "Path to .env file (default: .env)"],
+    ["--port <number>", "Server port (default: 4000)"],
+  ],
 };
 
 /**