db-model-router 1.0.3 → 1.0.4

package/src/cli/commands/help.js

@@ -0,0 +1,180 @@
+"use strict";
+
+/**
+ * Per-command detailed help text.
+ * Each key matches a subcommand name from main.js.
+ */
+const COMMAND_HELP = {
+  init: `Usage: db-model-router init [options]
+
+Scaffold a new project from a schema file or interactively.
+Creates app.js, .env, commons/, route/, middleware/, and migrations/.
+
+Options:
+  --from <path>          Read adapter, framework, and options from a schema file
+  --framework <name>     Express framework: express, ultimate-express
+  --database <name>      Database adapter: mysql, mariadb, postgres, sqlite3, mongodb,
+                         mssql, cockroachdb, oracle, redis, dynamodb
+  --db <name>            Alias for --database
+  --session <type>       Session store: memory, redis, database
+  --output <dir>         Directory for backend source files (relative to cwd).
+                         package.json and app.js stay in root; commons/, route/,
+                         middleware/, and migrations/ go inside this folder.
+  --rateLimiting         Enable rate limiting (default: yes)
+  --helmet               Enable Helmet security headers (default: yes)
+  --logger               Enable Winston + Loki logger for Grafana (default: yes)
+  --yes                  Accept all defaults without prompting
+  --json                 Output machine-readable JSON
+  --dry-run              Preview planned files without writing
+  --no-install           Skip npm install after scaffolding
+  --help                 Show this help message
+
+Generated files:
+  app.js                              Express app entry point
+  .env / .env.example                 Environment configuration
+  .gitignore                          Git ignore rules
+  <output>/commons/db.js              Database init, connect, and global.db
+  <output>/commons/session.js         Session configuration
+  <output>/commons/migrate.js         Migration runner (also runs as script)
+  <output>/commons/add_migration.js   Migration creation helper (also runs as script)
+  <output>/commons/security.js        Helmet, rate limiting, custom headers
+  <output>/middleware/logger.js        Winston + Loki request logger
+  <output>/route/index.js             Central route mounting
+  <output>/route/health.js            GET /health endpoint
+  <output>/migrations/                Initial migration files
+
+Examples:
+  db-model-router init --from dbmr.schema.json --yes --no-install
+  db-model-router init --framework express --database postgres --output backend --yes
+  db-model-router init --database mysql --session redis --helmet --rateLimiting
+  db-model-router init --dry-run`,
+
+  inspect: `Usage: db-model-router inspect [options]
+
+Introspect a live database and produce a dbmr.schema.json file.
+Connects to the database, reads table structures, and outputs a schema.
+
+Options:
+  --type <adapter>       Database adapter (required): mysql, postgres, sqlite3,
+                         mssql, oracle, cockroachdb
+  --env <path>           Path to .env file for connection parameters
+  --out <path>           Output file path (default: dbmr.schema.json)
+  --tables <list>        Comma-separated list of tables to include (omit for all)
+  --yes                  Accept all defaults without prompting
+  --json                 Output schema as JSON to stdout (no file write)
+  --dry-run              Output schema to stdout without writing file
+  --help                 Show this help message
+
+Examples:
+  db-model-router inspect --type postgres --env .env
+  db-model-router inspect --type sqlite3 --out schema.json --tables users,posts
+  db-model-router inspect --type mysql --json`,
+
+  generate: `Usage: db-model-router generate [options]
+
+Generate models, routes, tests, OpenAPI spec, and LLM docs from a schema file.
+When no artifact flags are provided, all artifact types are generated.
+
+Options:
+  --from <path>          Path to schema file (default: dbmr.schema.json)
+  --models               Generate only model files
+  --routes               Generate only route files (including child routes and index)
+  --openapi              Generate only OpenAPI spec
+  --tests                Generate only test files
+  --llm-docs             Generate only LLM documentation (llms.txt + docs/llm.md)
+  --yes                  Accept all defaults without prompting
+  --json                 Output machine-readable JSON
+  --dry-run              Report planned files without writing
+  --help                 Show this help message
+
+Generated files:
+  models/<table>.js                        Model with CRUD operations
+  routes/<table>.js                        Express route handlers
+  routes/<child>_child_of_<parent>.js      Child route (scoped by FK)
+  routes/index.js                          Route mounting index
+  test/<table>.test.js                     CRUD endpoint tests
+  openapi.json                             OpenAPI 3.0 spec
+  llms.txt                                 LLM quick reference
+  docs/llm.md                              Full LLM reference
+
+Examples:
+  db-model-router generate --from dbmr.schema.json
+  db-model-router generate --models --dry-run
+  db-model-router generate --routes --tests
+  db-model-router generate --from dbmr.schema.json --json`,
+
+  doctor: `Usage: db-model-router doctor [options]
+
+Validate schema, check adapter driver dependencies, and verify generated
+files are in sync with the schema.
+
+Options:
+  --from <path>          Path to schema file (default: dbmr.schema.json)
+  --yes                  Accept all defaults without prompting
+  --json                 Output machine-readable JSON
+  --help                 Show this help message
+
+Checks performed:
+  1. Schema validation    Syntax and structure of dbmr.schema.json
+  2. Dependency check     Adapter driver present in package.json
+  3. Sync check           Generated files match what the schema would produce
+
+Examples:
+  db-model-router doctor --from dbmr.schema.json
+  db-model-router doctor --json`,
+
+  diff: `Usage: db-model-router diff [options]
+
+Preview changes between the current generated files and what the schema
+would produce. Read-only — does not modify any files on disk.
+
+Options:
+  --from <path>          Path to schema file (default: dbmr.schema.json)
+  --yes                  Accept all defaults without prompting
+  --json                 Output machine-readable JSON
+  --help                 Show this help message
+
+Output shows:
+  + Added      New files that would be created
+  ~ Modified   Files with changes (includes line diffs)
+  - Deleted    Extra files that would be removed
+
+Examples:
+  db-model-router diff --from dbmr.schema.json
+  db-model-router diff --json`,
+};
+
+/**
+ * Help command handler.
+ *
+ * When called with a command name in args (e.g. `help init`), prints
+ * detailed help for that command. Otherwise prints the general overview.
+ *
+ * @param {object} args - Parsed key-value args
+ * @param {object} flags - Universal flags
+ * @param {import('../flags').OutputContext} ctx - Output context
+ * @param {object} options - Injected dependencies
+ * @param {Function} options.printHelp - General help printer from main.js
+ */
+async function help(args, flags, ctx, options) {
+  // The command to get help for is the first positional arg captured
+  // by parseFlags as a key-value. We also check args._command which
+  // main.js will inject.
+  const topic = args._command;
+
+  if (topic && COMMAND_HELP[topic]) {
+    ctx.log(COMMAND_HELP[topic]);
+  } else if (topic) {
+    ctx.log(`Unknown command: ${topic}\n`);
+    ctx.log(`Available commands: ${Object.keys(COMMAND_HELP).join(", ")}\n`);
+    ctx.log(`Run "db-model-router help <command>" for detailed help.`);
+  } else {
+    // No topic — print general help
+    if (options && options.printHelp) {
+      options.printHelp();
+    }
+  }
+}
+
+module.exports = help;
+module.exports.COMMAND_HELP = COMMAND_HELP;

package/src/cli/commands/init.js

@@ -19,9 +19,10 @@ const DEFAULT_ANSWERS = {
   framework: "express",
   database: "postgres",
   session: "memory",
-  rateLimiting: false,
-  helmet: false,
-  logger: false,
+  rateLimiting: true,
+  helmet: true,
+  logger: true,
+  loki: false,
 };
 
 /**
@@ -52,6 +53,7 @@ async function init(args, flags, ctx) {
       rateLimiting: !!(schema.options && schema.options.rateLimiting),
       helmet: !!(schema.options && schema.options.helmet),
       logger: !!(schema.options && schema.options.logger),
+      loki: !!(schema.options && schema.options.loki),
     };
   } else if (flags.yes) {
     // --yes with no schema: use defaults, but allow CLI overrides
@@ -66,9 +68,13 @@ async function init(args, flags, ctx) {
     answers = await promptUser(prefilled);
   }
 
+  // Resolve --output directory (relative to cwd)
+  // CLI --output flag takes precedence, then interactive prompt answer
+  const outputDir = args.output || answers.output || "";
+
   // --dry-run: report planned files without writing
   if (flags.dryRun) {
-    const planned = planFiles(answers);
+    const planned = planFiles(answers, outputDir);
     if (flags.json) {
       ctx.result({
         files: planned,
@@ -89,10 +95,10 @@ async function init(args, flags, ctx) {
   ensurePackageJson();
 
   // Generate project files
-  const generated = generateFiles(answers);
+  const generated = generateFiles(answers, outputDir);
 
   // Update package.json with deps and scripts
-  updatePackageJson(answers);
+  updatePackageJson(answers, outputDir);
 
   // npm install (unless --no-install)
   const installed = !flags.noInstall;
@@ -103,7 +109,10 @@ async function init(args, flags, ctx) {
   // Output
   const allFiles = [
     ...generated.files,
-    ...generated.migrationFiles.map((m) => `migrations/${m}`),
+    ...generated.migrationFiles.map((m) => {
+      const base = outputDir || ".";
+      return base === "." ? `migrations/${m}` : `${base}/migrations/${m}`;
+    }),
   ];
 
   if (flags.json) {
@@ -127,24 +136,43 @@ async function init(args, flags, ctx) {
  * This mirrors the file list from generateFiles() without writing anything.
  *
  * @param {object} answers
+ * @param {string} [outputDir] - relative output directory for source files
  * @returns {string[]}
  */
-function planFiles(answers) {
+function planFiles(answers, outputDir) {
   const { isSql } = require("../init/generators");
+  const srcBase = outputDir || ".";
+  const prefix = srcBase === "." ? "" : srcBase + "/";
+
   const files = [
     "app.js",
     ".env",
     ".env.example",
-    "middleware/logger.js",
-    "migrate.js",
-    "add_migration.js",
     ".gitignore",
-    "migrations/<timestamp>_create_migrations_table" +
-      (isSql(answers.database) ? ".sql" : ".js"),
+    "Dockerfile",
+    ".dockerignore",
   ];
 
+  // docker-compose.yml for databases that need Docker
+  if (answers.database !== "sqlite3") {
+    files.push("docker-compose.yml");
+  }
+
+  files.push(
+    `${prefix}middleware/logger.js`,
+    `${prefix}commons/session.js`,
+    `${prefix}commons/migrate.js`,
+    `${prefix}commons/add_migration.js`,
+    `${prefix}commons/security.js`,
+    `${prefix}commons/db.js`,
+    `${prefix}route/health.js`,
+    `${prefix}route/index.js`,
+    `${prefix}migrations/<timestamp>_create_migrations_table` +
+      (isSql(answers.database) ? ".sql" : ".js"),
+  );
+
   if (answers.session === "database" && isSql(answers.database)) {
-    files.push("migrations/<timestamp>_create_sessions_table.sql");
+    files.push(`${prefix}migrations/<timestamp>_create_sessions_table.sql`);
   }
 
   return files;

package/src/cli/commands/inspect.js

@@ -40,15 +40,32 @@ function modelMetaToSchema(adapter, framework, models) {
   for (const m of models) {
     const columns = {};
 
-    // Re-add columns from structure
+    const pk = m.primary_key || "id";
+    const opt = m.option || {};
+
+    // Add PK column as auto_increment
+    columns[pk] = "auto_increment";
+
+    // Add timestamp columns as datetime
+    if (opt.created_at) {
+      columns[opt.created_at] = "datetime";
+    }
+    if (opt.modified_at) {
+      columns[opt.modified_at] = "datetime";
+    }
+
+    // Add softDelete column
+    if (opt.safeDelete) {
+      columns[opt.safeDelete] = "boolean";
+    }
+
+    // Add remaining columns from structure
     for (const [col, rule] of Object.entries(m.structure)) {
       columns[col] = rule;
     }
 
-    const pk = m.primary_key || "id";
     const unique = m.unique && m.unique.length > 0 ? [...m.unique] : [pk];
 
-    const opt = m.option || {};
     const softDelete = opt.safeDelete || null;
     const timestamps = {
       created_at: opt.created_at || null,

package/src/cli/generate-model.js

@@ -475,7 +475,7 @@ function mysqlTypeToValidator(t) {
   if (/json/.test(t)) return "object";
   if (/text|char|varchar|enum|set/.test(t)) return "string";
   if (/blob|binary/.test(t)) return "string";
-  if (/date|time|year/.test(t)) return "string";
+  if (/date|time|year/.test(t)) return "datetime";
   if (/bool/.test(t)) return "integer";
   return "string";
 }
@@ -487,7 +487,7 @@ function pgTypeToValidator(t) {
   if (/json/.test(t)) return "object";
   if (/bool/.test(t)) return "integer";
   if (/char|text|varchar|uuid/.test(t)) return "string";
-  if (/date|time|interval/.test(t)) return "string";
+  if (/date|time|interval/.test(t)) return "datetime";
   return "string";
 }
 
@@ -496,6 +496,7 @@ function sqliteTypeToValidator(t) {
   if (/int/.test(t)) return "integer";
   if (/real|float|double|numeric|decimal/.test(t)) return "numeric";
   if (/json/.test(t)) return "object";
+  if (/date|time/.test(t)) return "datetime";
   if (/blob/.test(t)) return "string";
   return "string";
 }
@@ -506,7 +507,7 @@ function mssqlTypeToValidator(t) {
   if (/decimal|numeric|float|real|money/.test(t)) return "numeric";
   if (/bit/.test(t)) return "integer";
   if (/char|text|varchar|nchar|nvarchar|ntext/.test(t)) return "string";
-  if (/date|time|datetime/.test(t)) return "string";
+  if (/date|time|datetime/.test(t)) return "datetime";
   if (/uniqueidentifier/.test(t)) return "string";
   return "string";
 }
@@ -515,7 +516,7 @@ function oracleTypeToValidator(t) {
   if (/NUMBER|INTEGER|FLOAT|BINARY_FLOAT|BINARY_DOUBLE/.test(t))
     return "numeric";
   if (/CLOB|BLOB|RAW|LONG/.test(t)) return "string";
-  if (/DATE|TIMESTAMP/.test(t)) return "string";
+  if (/DATE|TIMESTAMP/.test(t)) return "datetime";
   if (/CHAR|VARCHAR|NCHAR|NVARCHAR/.test(t)) return "string";
   return "string";
 }

package/src/cli/generate-route.js

@@ -25,10 +25,12 @@ function safeVarName(name) {
  */
 function generateRouteFile(tableName, modelsRelPath) {
   const varName = safeVarName(tableName);
-  return `const { route } = require("db-model-router");
-const ${varName} = require("${modelsRelPath}/${tableName}");
+  return `import dbModelRouter from "db-model-router";
+import ${varName} from "${modelsRelPath}/${tableName}.js";
 
-module.exports = route(${varName});
+const { route } = dbModelRouter;
+
+export default route(${varName});
 `;
 }
 
@@ -43,11 +45,13 @@ function generateChildRouteFile(
   modelsRelPath,
 ) {
   const varName = safeVarName(childTable);
-  return `const { route } = require("db-model-router");
-const ${varName} = require("${modelsRelPath}/${childTable}");
+  return `import dbModelRouter from "db-model-router";
+import ${varName} from "${modelsRelPath}/${childTable}.js";
+
+const { route } = dbModelRouter;
 
 // Child route: scoped by parent ${parentTable} via ${fkColumn}
-module.exports = route(${varName}, { ${fkColumn}: "params.${fkColumn}" });
+export default route(${varName}, { ${fkColumn}: "params.${fkColumn}" });
 `;
 }
 
@@ -56,7 +60,7 @@ module.exports = route(${varName}, { ${fkColumn}: "params.${fkColumn}" });
  * Supports parent-child nesting: parent/:pk/child
  */
 function generateRoutesIndexFile(tableNames, relationships = []) {
-  let imports = `let express;\ntry { express = require("ultimate-express"); } catch (_) { express = require("express"); }\nconst router = express.Router();\n\n`;
+  let imports = `import express from "express";\n\nconst router = express.Router();\n\n`;
 
   // Collect child tables that are nested under parents
   const nestedChildren = new Set();
@@ -66,12 +70,12 @@ function generateRoutesIndexFile(tableNames, relationships = []) {
 
   for (const table of tableNames) {
     const varName = safeVarName(table);
-    imports += `const ${varName}Route = require("./${table}");\n`;
+    imports += `import ${varName}Route from "./${table}.js";\n`;
   }
   // Import child routes with _child suffix for nested ones
   for (const rel of relationships) {
     const varName = safeVarName(rel.child);
-    imports += `const ${varName}ChildRoute = require("./${rel.child}_child_of_${rel.parent}");\n`;
+    imports += `import ${varName}ChildRoute from "./${rel.child}_child_of_${rel.parent}.js";\n`;
   }
 
   imports += "\n";
@@ -85,9 +89,7 @@ function generateRoutesIndexFile(tableNames, relationships = []) {
 
   // Mount nested child routes under parent
   for (const rel of relationships) {
-    const parentVar = safeVarName(rel.parent);
     const childVar = safeVarName(rel.child);
-    // Find parent PK from model file name convention — use fkColumn without _id suffix as parent pk param
     imports += `router.use("/${rel.parent}/:${rel.fkColumn}/${rel.child}", ${childVar}ChildRoute);\n`;
   }
 
@@ -97,7 +99,7 @@ function generateRoutesIndexFile(tableNames, relationships = []) {
     imports += `router.use("/${rel.child}", ${varName}Route);\n`;
   }
 
-  imports += "\nmodule.exports = router;\n";
+  imports += "\nexport default router;\n";
   return imports;
 }
 
@@ -114,13 +116,15 @@ function generateSimpleRoutesIndexFile(tableNames) {
  */
 function generateTestFile(tableName, pk) {
   const varName = safeVarName(tableName);
-  return `const assert = require("assert");
-const express = require("express");
-const request = require("supertest");
-const { route } = require("db-model-router");
+  return `import assert from "assert";
+import express from "express";
+import request from "supertest";
+import dbModelRouter from "db-model-router";
+
+const { route } = dbModelRouter;
 
 // Adjust the path to your model file as needed
-const ${varName} = require("../models/${tableName}");
+import ${varName} from "../models/${tableName}.js";
 
 function createApp() {
   const app = express();
@@ -220,12 +224,14 @@ describe("${tableName} routes", function () {
  */
 function generateChildTestFile(childTable, parentTable, fkColumn, pk) {
   const childVar = safeVarName(childTable);
-  return `const assert = require("assert");
-const express = require("express");
-const request = require("supertest");
-const { route } = require("db-model-router");
+  return `import assert from "assert";
+import express from "express";
+import request from "supertest";
+import dbModelRouter from "db-model-router";
+
+const { route } = dbModelRouter;
 
-const ${childVar} = require("../models/${childTable}");
+import ${childVar} from "../models/${childTable}.js";
 
 function createApp() {
   const app = express();

package/src/cli/init/dependencies.js

@@ -5,6 +5,7 @@
  */
 const DRIVER_MAP = {
   mysql: ["mysql2"],
+  mariadb: ["mysql2"],
   postgres: ["pg"],
   sqlite3: ["better-sqlite3"],
   mongodb: ["mongodb"],
@@ -53,7 +54,10 @@ function collectDependencies(answers) {
     dependencies["helmet"] = "latest";
   }
   if (answers.logger) {
-    dependencies["express-mung"] = "latest";
+    dependencies["winston"] = "latest";
+    if (answers.loki) {
+      dependencies["winston-loki"] = "latest";
+    }
   }
 
   // Dev dependencies
@@ -63,16 +67,21 @@ function collectDependencies(answers) {
 }
 
 /**
- * Returns the 5 package.json scripts.
+ * Returns the package.json scripts.
+ * @param {string} [outputDir] - relative output directory for source files
  * @returns {Record<string, string>}
  */
-function getScripts() {
+function getScripts(outputDir) {
+  const prefix = outputDir ? `${outputDir}/` : "";
   return {
     start: "node app.js",
     dev: "nodemon app.js",
     test: 'echo "Error: no test specified" && exit 1',
-    migrate: "node migrate.js",
-    add_migration: "node add_migration.js",
+    migrate: `node ${prefix}commons/migrate.js`,
+    add_migration: `node ${prefix}commons/add_migration.js`,
+    "docker:build": "docker build -t app .",
+    "docker:up": "docker compose up -d",
+    "docker:down": "docker compose down",
   };
 }