db-model-router 1.0.3 → 1.0.5

package/skill/references/oracle.md

@@ -0,0 +1,52 @@
+# Oracle Adapter
+
+Uses [oracledb](https://www.npmjs.com/package/oracledb) (Oracle Instant Client required).
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("oracle");
+
+db.connect({
+  host: "localhost",
+  port: 1521,
+  database: "XEPDB1",
+  user: "system",
+  password: "oracle",
+});
+```
+
+## Environment Variables
+
+```env
+ORACLE_HOST=localhost
+ORACLE_PORT=1521
+ORACLE_DB=XEPDB1
+ORACLE_USER=system
+ORACLE_PASSWORD=oracle
+```
+
+## Notes
+
+- Requires Oracle Instant Client installed on the host
+- Uses connection pooling with session callbacks for NLS date format
+- MySQL-style `?` placeholders are auto-translated to `:1, :2, ...`
+- Includes a SQL translator that converts MySQL DDL/DML to Oracle syntax
+- `MERGE INTO ... USING DUAL` is used for upsert operations
+- `RETURNING ... INTO :pk_out` is used to retrieve auto-generated IDs
+- Oracle reserved words in column names are auto-quoted
+- `CLOB` values are fetched as strings
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name VARCHAR2(255) NOT NULL,
+  email VARCHAR2(255) NOT NULL,
+  age NUMBER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/postgres.md

@@ -0,0 +1,50 @@
+# PostgreSQL Adapter
+
+Uses the [pg](https://www.npmjs.com/package/pg) driver with connection pooling.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("postgres");
+
+db.connect({
+  host: "localhost",
+  port: 5432,
+  user: "postgres",
+  password: "password",
+  database: "my_app",
+  connectionLimit: 50, // pool max
+  dateStrings: false, // set true to return dates as strings
+});
+```
+
+## Environment Variables
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=password
+PG_DB=test_db
+```
+
+## Notes
+
+- Supports MySQL-style `?` placeholders in raw `db.query()` calls — they are auto-translated to `$1, $2, ...`
+- `SERIAL` / `BIGSERIAL` primary keys are auto-detected via `pg_index`
+- `ON CONFLICT` is used for upsert operations
+- Includes a SQL translator layer that converts common MySQL DDL/DML to PostgreSQL syntax
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR NOT NULL,
+  email VARCHAR NOT NULL,
+  age INTEGER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/redis.md

@@ -0,0 +1,53 @@
+# Redis Adapter
+
+Uses [ioredis](https://www.npmjs.com/package/ioredis). Records are stored as Redis hashes with key pattern `{table}:{id}`.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("redis");
+
+db.connect({
+  host: "localhost",
+  port: 6379,
+  password: "", // optional
+  db: 0, // Redis DB index, optional
+  primaryKey: "id", // field used as the hash key suffix
+});
+```
+
+## Environment Variables
+
+```env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+## Notes
+
+- Each record is a Redis hash at key `{table}:{primaryKey}`
+- Auto-incrementing IDs use `INCR {table}:__seq`
+- All filtering, sorting, and pagination happen in-memory (full SCAN)
+- Redis stores all values as strings — numeric coercion is applied on read
+- Nested objects are JSON-serialized into hash fields
+- Best suited for small-to-medium datasets where Redis is already in the stack
+
+## Model Definition
+
+```js
+const users = model(
+  db,
+  "users",
+  {
+    id: "string",
+    name: "required|string",
+    email: "required|string",
+    age: "required|integer",
+  },
+  "id",
+  ["id"],
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/sqlite3.md

@@ -0,0 +1,43 @@
+# SQLite3 Adapter
+
+Uses [better-sqlite3](https://www.npmjs.com/package/better-sqlite3) for synchronous, high-performance SQLite access.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("sqlite3");
+
+db.connect({ database: "./data.db" });
+// or in-memory:
+db.connect({ database: ":memory:" });
+```
+
+## Options
+
+| Option          | Description                 |
+| --------------- | --------------------------- |
+| `database`      | File path or `:memory:`     |
+| `readonly`      | Open in read-only mode      |
+| `fileMustExist` | Throw if file doesn't exist |
+
+## Notes
+
+- All operations are synchronous (wrapped to match the async model API)
+- WAL journal mode is enabled by default for better concurrency
+- Uses `INSERT OR IGNORE` for conflict handling
+- `ON CONFLICT ... DO UPDATE SET` for upsert
+- No Docker container needed — runs in-process
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL,
+  age INTEGER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/src/cli/commands/generate.js

@@ -14,21 +14,26 @@ const {
 } = require("../generate-route");
 const { generateOpenAPISpec } = require("../generate-openapi");
 const { generateLlmsTxt, generateLlmMd } = require("./generate-llm-docs");
+const { generateMigrationFiles } = require("../generate-migration");
+const { generateDocsRoute } = require("../generate-docs-route");
+const { migrationTimestamp } = require("../init/generators");
 
 /**
  * Generate command handler for the unified CLI.
  *
  * Reads a schema file, converts to ModelMeta[], and generates
- * models, routes, tests, and OpenAPI spec files.
+ * models, routes, tests, OpenAPI spec, migrations, and docs route.
  *
  * Supported flags:
- *   --from      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
- *   --dry-run   Report planned files without writing
- *   --json      Output JSON result via ctx
+ *   --from        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 + docs route
+ *   --tests       Generate only test files
+ *   --migrations  Generate only migration files
+ *   --llm-docs    Generate only LLM documentation
+ *   --dry-run     Report planned files without writing
+ *   --json        Output JSON result via ctx
  *
  * When no artifact flags are provided, all artifact types are generated.
  *
@@ -80,12 +85,14 @@ async function generate(args, flags, ctx) {
     args.routes === true ||
     args.openapi === true ||
     args.tests === true ||
+    args.migrations === true ||
     args["llm-docs"] === true;
 
   const genModels = !hasArtifactFlag || args.models === true;
   const genRoutes = !hasArtifactFlag || args.routes === true;
   const genOpenapi = !hasArtifactFlag || args.openapi === true;
   const genTests = !hasArtifactFlag || args.tests === true;
+  const genMigrations = !hasArtifactFlag || args.migrations === true;
   const genLlmDocs = !hasArtifactFlag || args["llm-docs"] === true;
 
   const modelsRelPath = "../models";
@@ -106,57 +113,91 @@ async function generate(args, flags, ctx) {
 
   // --- Route files ---
   if (genRoutes) {
-    // One route per table
+    // Collect child tables to skip generating top-level route files for them
+    const nestedChildren = new Set();
+    for (const rel of relationships) {
+      nestedChildren.add(rel.child);
+    }
+
+    // One route per top-level table (skip children)
     for (const m of meta) {
+      if (nestedChildren.has(m.table)) continue;
       planned.push({
         relPath: `routes/${m.table}.js`,
         content: generateRouteFile(m.table, modelsRelPath),
       });
     }
 
-    // Child route files (one per relationship)
+    // Child route files in subfolders: routes/<parent>/<child>.js
     for (const rel of relationships) {
       planned.push({
-        relPath: `routes/${rel.child}_child_of_${rel.parent}.js`,
+        relPath: `routes/${rel.parent}/${rel.child}.js`,
         content: generateChildRouteFile(
           rel.child,
           rel.parent,
           rel.foreignKey,
-          modelsRelPath,
+          `../../models`,
         ),
       });
     }
 
-    // Routes index file
+    // Routes index file (include docs route when openapi is being generated)
     planned.push({
       relPath: "routes/index.js",
-      content: generateRoutesIndexFile(tableNames, relationships),
+      content: generateRoutesIndexFile(tableNames, relationships, {
+        includeDocs: genOpenapi,
+      }),
     });
   }
 
-  // --- OpenAPI spec ---
+  // --- OpenAPI spec + docs route ---
   if (genOpenapi) {
     planned.push({
       relPath: "openapi.json",
       content: JSON.stringify(generateOpenAPISpec(meta), null, 2) + "\n",
     });
+
+    // Generate Swagger UI docs route
+    planned.push({
+      relPath: "routes/docs.js",
+      content: generateDocsRoute(),
+    });
+  }
+
+  // --- Migration files ---
+  if (genMigrations) {
+    const migrationFiles = generateMigrationFiles(schema);
+    const ts = migrationTimestamp(new Date());
+    for (const mf of migrationFiles) {
+      planned.push({
+        relPath: `migrations/${ts}_${mf.filename}`,
+        content: mf.content,
+      });
+    }
   }
 
   // --- Test files ---
   if (genTests) {
+    // Collect child tables to skip generating top-level test files for them
+    const nestedChildrenForTests = new Set();
+    for (const rel of relationships) {
+      nestedChildrenForTests.add(rel.child);
+    }
+
     for (const m of meta) {
+      if (nestedChildrenForTests.has(m.table)) continue;
       planned.push({
         relPath: `test/${m.table}.test.js`,
         content: generateTestFile(m.table, m.primary_key),
       });
     }
 
-    // Child test files (one per relationship)
+    // Child test files in subfolders: test/<parent>/<child>.test.js
     for (const rel of relationships) {
       const childMeta = meta.find((m) => m.table === rel.child);
       const pk = childMeta ? childMeta.primary_key : "id";
       planned.push({
-        relPath: `test/${rel.child}_child_of_${rel.parent}.test.js`,
+        relPath: `test/${rel.parent}/${rel.child}.test.js`,
         content: generateChildTestFile(
           rel.child,
           rel.parent,

package/src/cli/commands/help.js

@@ -0,0 +1,185 @@
+"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/, routes/, 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/, routes/,
+                         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>/routes/index.js             Central route mounting
+  <output>/routes/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 + Swagger UI docs route
+  --tests                Generate only test files
+  --migrations           Generate only database migration 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/<parent>/<child>.js               Child route (scoped by FK)
+  routes/docs.js                           Swagger UI at /docs
+  routes/index.js                          Route mounting index
+  migrations/<timestamp>_create_tables.sql Database migration (SQL adapters)
+  migrations/<timestamp>_create_<t>.js     Database migration (NoSQL adapters)
+  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 --migrations
+  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}routes/health.js`,
+    `${prefix}routes/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,
@@ -62,6 +79,7 @@ function modelMetaToSchema(adapter, framework, models) {
       unique,
       softDelete,
       timestamps,
+      parent: null,
     };
   }