db-model-router 1.0.0 → 1.0.3

package/docs/SKILL.md

@@ -1,15 +1,45 @@
+---
+name: db-model-router
+description: Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API. Works with express or ultimate-express.
+---
+
 # db-model-router — LLM Skill Reference
 
-Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API.
+Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API. Works with `express` or `ultimate-express`.
+
+## LLM Workflow (follow this order)
+
+1. **Scaffold**: `db-model-router-init --framework express --database postgres --session redis --rateLimiting --helmet --logger` (all flags → zero prompts)
+2. **Migrations**: Write SQL/JS migration files into `migrations/` for the user's schema, then `npm run migrate`
+3. **Generate models**: `db-model-router-generate-model --type postgres --env .env --output ./models`
+4. **Generate routes + tests**: `db-model-router-generate-route --models ./models --output ./routes --tables users,posts,posts.comments`
+5. **Run**: `npm run dev`
+
+Step 1 creates the project. Step 2 defines the schema. Steps 3-4 introspect the DB and generate models, routes, tests, and OpenAPI spec. Step 5 starts the server.
 
 ## Install
 
 ```bash
-npm install db-model-router <driver>
+npm install db-model-router <framework> <driver>
 ```
 
+Frameworks: `express` or `ultimate-express` (auto-detected, prefers ultimate-express)
 Drivers: `mysql2`, `pg`, `better-sqlite3`, `mongodb`, `mssql`, `oracledb`, `ioredis`, `@aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`
 
+## Adapters
+
+| Module Key    | Driver                                           | Default Port |
+| ------------- | ------------------------------------------------ | ------------ |
+| `mysql`       | mysql2                                           | 3306         |
+| `postgres`    | pg                                               | 5432         |
+| `sqlite3`     | better-sqlite3                                   | —            |
+| `mongodb`     | mongodb                                          | 27017        |
+| `mssql`       | mssql                                            | 1433         |
+| `cockroachdb` | pg                                               | 26257        |
+| `oracle`      | oracledb                                         | 1521         |
+| `redis`       | ioredis                                          | 6379         |
+| `dynamodb`    | @aws-sdk/client-dynamodb + @aws-sdk/lib-dynamodb | —            |
+
 ## Init → Connect → Model → Route
 
 ```js
@@ -42,12 +72,12 @@ app.use("/users", route(users));
 
 ## model(db, table, structure, pk, unique, option)
 
-| Param     | Type            | Description                                                                                                           |
-| --------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
-| structure | `{col: "rule"}` | Types: `string\|integer\|numeric\|object`. Prefix `required\|` for NOT NULL. Exclude PK, timestamps, soft-delete cols |
-| pk        | string          | Primary key column. Default `"id"`                                                                                    |
-| unique    | string[]        | Columns for upsert conflict resolution                                                                                |
-| option    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                      |
+| Param     | Type            | Description                                                                                                                    |
+| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| structure | `{col: "rule"}` | Types: `string\|integer\|numeric\|boolean\|object`. Prefix `required\|` for NOT NULL. Exclude PK, timestamps, soft-delete cols |
+| pk        | string          | Primary key column. Default `"id"`                                                                                             |
+| unique    | string[]        | Columns for upsert conflict resolution                                                                                         |
+| option    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                               |
 
 ## Model Methods (all async)
 
@@ -83,14 +113,22 @@ Structure: `[OR_groups[AND_conditions[col, op, val]]]`
 Ops: `= != < > <= >= like not like in not in`
 
 ```js
+// AND: age > 25 AND type = 1
 [
   [
     ["age", ">", 25],
     ["type", "=", 1],
   ],
-][([["name", "=", "A"]], [["name", "=", "B"]])][[["type", "in", [1, 2, 3]]]][ // AND // OR // IN
+][
+  // OR: name = "A" OR name = "B"
+  ([["name", "=", "A"]], [["name", "=", "B"]])
+][
+  // IN
+  [["type", "in", [1, 2, 3]]]
+][
+  // LIKE (auto-wraps with %)
   [["name", "like", "Ali"]]
-]; // LIKE %Ali%
+];
 ```
 
 ## route(model, override?)
@@ -100,14 +138,14 @@ Generates Express Router with 9 endpoints:
 | Method | Path   | Action                           |
 | ------ | ------ | -------------------------------- |
 | GET    | `/:pk` | Get by PK                        |
-| POST   | `/:id` | Insert single                    |
-| PUT    | `/:id` | Update single (PK from URL)      |
-| PATCH  | `/:id` | Partial update                   |
-| DELETE | `/:id` | Delete single                    |
+| POST   | `/add` | Insert single                    |
+| PUT    | `/:pk` | Update single (PK from URL)      |
+| PATCH  | `/:pk` | Partial update (PK from URL)     |
+| DELETE | `/:pk` | Delete single                    |
 | GET    | `/`    | List (page, size, sort, filters) |
 | POST   | `/`    | Bulk insert `{data:[...]}`       |
 | PUT    | `/`    | Bulk update `{data:[...]}`       |
-| DELETE | `/`    | Bulk delete `{data:[...]}`       |
+| DELETE | `/`    | Bulk delete                      |
 
 **Payload override** (multi-tenancy): `route(m, { tenant_id: "user.tenant_id" })` — maps cols to `req` paths via lodash.get.
 
@@ -115,29 +153,94 @@ Generates Express Router with 9 endpoints:
 
 ## CLI Tools
 
-### generate-app (full scaffold)
+### db-model-router-init (interactive project scaffold)
+
+Scaffolds a complete Express-based REST API project from scratch. Supports both interactive prompts and fully non-interactive CLI flags.
 
 ```bash
-rest-router-generate-app --type mysql --env .env [--output ./dir] [--tables users,posts,posts.comments]
+# Interactive (prompts for everything)
+npx db-model-router-init
+
+# Fully non-interactive (LLM-friendly — no prompts)
+db-model-router-init --framework express --database postgres --session redis --rateLimiting --helmet --logger
+
+# Partial flags — only prompts for missing values
+db-model-router-init --database mysql --session memory
 ```
 
-Creates: `app.js`, `models/`, `routes/`, `middleware/logger.js`, `.env.example`, `.gitignore`, `migrations/`, `sessions/`, `openapi.json`
+Flags: `--framework <name>`, `--database <name>` (or `--db`), `--session <type>`, `--rateLimiting`, `--helmet`, `--logger`, `--help`
+
+When all 6 options are provided, runs with zero prompts.
+
+Prompts (for missing values): framework (`ultimate-express`|`express`), database (9 options), session (`memory`|`redis`|`database`), rate limiting (y/n), helmet (y/n), logger (y/n).
+
+If no `package.json` exists, runs `npm init` first. After prompts: generates files, updates `package.json`, runs `npm install`.
+
+Generated structure:
+
+```
+app.js, .env, .env.example, .gitignore, migrate.js, add_migration.js,
+middleware/logger.js, migrations/{timestamp}_create_migrations_table.sql|.js
+```
+
+Session migration (`{timestamp}_create_sessions_table.sql`) generated only for SQL databases with `session=database`.
+
+Scripts added: `start` (node app.js), `dev` (nodemon app.js), `test`, `migrate` (node migrate.js), `add_migration` (node add_migration.js).
+
+Dependencies always included: `db-model-router`, `dotenv`, selected framework, database driver(s), `express-session`. DevDeps: `nodemon`.
+Conditional: `connect-redis` + `ioredis` (session=redis), `express-rate-limit`, `helmet`, `express-mung` (logger).
+
+#### Environment Variables by Database
+
+| Database    | Variables                                                                   |
+| ----------- | --------------------------------------------------------------------------- |
+| mysql       | `PORT=3000 DB_HOST DB_PORT=3306 DB_NAME DB_USER DB_PASS`                    |
+| postgres    | `PORT=3000 DB_HOST DB_PORT=5432 DB_NAME DB_USER DB_PASS`                    |
+| cockroachdb | `PORT=3000 DB_HOST DB_PORT=26257 DB_NAME DB_USER DB_PASS`                   |
+| sqlite3     | `PORT=3000 DB_NAME=./data.db`                                               |
+| mongodb     | `PORT=3000 DB_HOST DB_PORT=27017 DB_NAME DB_USER DB_PASS`                   |
+| mssql       | `PORT=3000 DB_HOST DB_PORT=1433 DB_NAME DB_USER DB_PASS`                    |
+| oracle      | `PORT=3000 DB_HOST DB_PORT=1521 DB_NAME DB_USER DB_PASS`                    |
+| redis       | `PORT=3000 DB_HOST DB_PORT=6379 DB_PASS`                                    |
+| dynamodb    | `PORT=3000 AWS_REGION AWS_ENDPOINT AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY` |
+
+When `session=redis` and database ≠ redis: adds `REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASS`.
+
+#### Migration Infrastructure
+
+- `migrate.js` — reads `migrations/` dir, diffs against `_migrations` tracking table, executes pending in order
+- `add_migration.js` — creates timestamped empty migration (`.sql` for SQL, `.js` for NoSQL)
+- Tracking table `_migrations`: `{id, filename, executed_at, checksum}` (SQL) or equivalent collection/hash/table (NoSQL)
+- Timestamp format: `YYYYMMDDHHMMSS`
 
 ### generate-model (DB introspection → model files)
 
 ```bash
-rest-router-generate-model --type <db> --env .env [--output ./models] [--tables t1,t2] [--schema public]
+db-model-router-generate-model --type <db> --env .env [--output ./models] [--tables t1,t2] [--schema public]
 ```
 
-Auto-detects: PK, unique indexes, DEFAULT→optional, timestamp cols, soft-delete cols.
+Options: `--type`, `--host`, `--port`, `--database`, `--user`, `--password`, `--schema`, `--output`, `--tables`, `--env`
+
+Auto-detects: PK, unique indexes, DEFAULT→optional, timestamp cols (`created_at`, `updated_at`, `modified_at`, `createdAt`, etc.), soft-delete cols (`is_deleted`, `deleted`, `is_active`, `archived`, etc.). Multi-column unique indexes correctly grouped.
 
-### generate-route (model files → route files + OpenAPI)
+### generate-route (model files → route files + tests + OpenAPI)
 
 ```bash
-rest-router-generate-route --models ./models --output ./routes [--tables posts,posts.comments]
+db-model-router-generate-route --models ./models --output ./routes [--tables posts,posts.comments]
 ```
 
-Dot notation `parent.child` creates nested routes: `parent/:parent_id/child` with FK scoping via `<parent_singular>_id`.
+Options: `--models`, `--output`, `--type`, `--host`, `--port`, `--database`, `--user`, `--password`, `--schema`, `--tables`, `--env`
+
+Generates:
+
+- Route files for each model
+- `index.js` mounting all routes on an Express Router
+- `openapi.json` (OpenAPI 3.0 spec)
+- Test files in `tests/` directory for all routes and methods (uses `supertest` + `assert`)
+
+Dot notation `parent.child` creates nested routes: `parent/:parent_id/child` with FK scoping via `<parent_singular>_id`. Also generates child route test files.
+
+Generated test files cover all 8 CRUD endpoints per table: GET by ID, POST add, PUT update, DELETE, list, bulk insert, bulk update, bulk delete.
 
 ## Connection Configs
 
@@ -192,7 +295,7 @@ db.connect({ region, endpoint, accessKeyId, secretAccessKey });
 ## Rules
 
 1. `init()` before `db.connect()`. Don't destructure `db` before `init()`.
-2. `modelStructure` excludes: PK col, timestamp cols, soft-delete cols.
+2. `model structure` excludes: PK col, timestamp cols, soft-delete cols.
 3. `update()`/`patch()` require PK in payload. `upsert()` PK is optional.
 4. `findOne()` returns `false` on no match. `byId()` returns `null`.
 5. Bulk ops wrap in `{ data: [...] }`. Single ops use flat object.
@@ -200,3 +303,72 @@ db.connect({ region, endpoint, accessKeyId, secretAccessKey });
 7. `safeDelete` makes `remove()` soft-delete; all reads auto-filter deleted rows.
 8. `list()` defaults: page=0, size=30. `sort` array: `["-col"]` for DESC.
 9. CommonJS only (`require`). Use dynamic `import()` for ESM.
+10. `db-model-router-init` for new projects (interactive). `generate-model` + `generate-route` for existing databases. Or use the unified `db-model-router` CLI with a `dbmr.schema.json` file.
+11. `generate-route` auto-generates test files alongside routes. Tests use `supertest`.
+
+## Schema-Driven Workflow (Unified CLI)
+
+The `db-model-router` command is the unified CLI entry point. It uses a single `dbmr.schema.json` file as the source of truth for all code generation.
+
+### LLM Workflow (schema-driven)
+
+1. **Inspect** (existing DB): `db-model-router inspect --type postgres --env .env` → writes `dbmr.schema.json`
+2. **Edit** `dbmr.schema.json` — add relationships, tweak columns, set options
+3. **Generate**: `db-model-router generate --from dbmr.schema.json` → models, routes, tests, OpenAPI
+4. **Doctor**: `db-model-router doctor --from dbmr.schema.json` → validate schema + check sync
+5. **Run**: `npm run dev`
+
+Or for new projects: `db-model-router init --from dbmr.schema.json --yes`
+
+### Subcommands
+
+| Subcommand | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `init`     | Scaffold project (optionally from schema file via `--from`) |
+| `inspect`  | Introspect live DB → produce `dbmr.schema.json`             |
+| `generate` | Generate models/routes/tests/OpenAPI from schema            |
+| `doctor`   | Validate schema, check deps, verify files in sync           |
+| `diff`     | Preview changes regeneration would make (read-only)         |
+
+### Universal Flags
+
+All subcommands accept: `--yes`, `--json`, `--dry-run`, `--no-install`, `--help`.
+
+- `--yes`: suppress prompts, accept defaults
+- `--json`: machine-readable JSON output only
+- `--dry-run`: preview without writing files
+- `--no-install`: skip `npm install`
+
+### dbmr.schema.json Format
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "name": "required|string",
+        "email": "required|string",
+        "age": "integer"
+      },
+      "pk": "id",
+      "unique": ["email"],
+      "softDelete": "is_deleted",
+      "timestamps": { "created_at": "created_at", "modified_at": "updated_at" }
+    }
+  },
+  "relationships": [
+    { "parent": "users", "child": "posts", "foreignKey": "user_id" }
+  ]
+}
+```
+
+Fields per table: `columns` (required), `pk` (default `"id"`), `unique` (default `[pk]`), `softDelete`, `timestamps`.
+Column rules: `(required|)?(string|integer|numeric|boolean|object)`.

package/docs/adapters/cockroachdb.md

@@ -46,4 +46,4 @@ CREATE TABLE users (
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/dynamodb.md

@@ -50,4 +50,4 @@ aws dynamodb create-table \
   --endpoint-url http://localhost:8000
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/mongodb.md

@@ -53,4 +53,4 @@ const users = model(
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/mssql.md

@@ -52,4 +52,4 @@ CREATE TABLE users (
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/oracle.md

@@ -49,4 +49,4 @@ CREATE TABLE users (
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/postgres.md

@@ -47,4 +47,4 @@ CREATE TABLE users (
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/redis.md

@@ -50,4 +50,4 @@ const users = model(
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/docs/adapters/sqlite3.md

@@ -40,4 +40,4 @@ CREATE TABLE users (
 );
 ```
 
-[← Back to main docs](../README.md)
+[← Back to main docs](../../README.md)

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "db-model-router",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Generative API Creation using mysql2 and express libraries in node js",
   "main": "src/index.js",
   "bin": {
-    "generate-model": "src/cli/generate-model.js",
-    "generate-route": "src/cli/generate-route.js",
-    "generate-app": "src/cli/generate-app.js"
+    "db-model-router": "src/cli/main.js"
   },
   "scripts": {
     "dev": "nodemon src/serve.js",
@@ -30,6 +28,7 @@
   "keywords": [
     "mysql2",
     "express",
+    "ultimate-express",
     "generative",
     "rest",
     "api"
@@ -42,22 +41,22 @@
   "homepage": "https://github.com/AvinashSKaranth/db-model-router#readme",
   "dependencies": {
     "dotenv": "^10.0.0",
+    "inquirer": "^8.2.6",
     "lodash": "^4.17.21",
     "node-input-validator": "^4.5.0"
   },
   "peerDependencies": {
-    "express": "^4.17.2 || ^5.0.0",
-    "ultimate-express": "^2.0.0",
-    "body-parser": "^1.20.0",
     "@aws-sdk/client-dynamodb": "^3.1029.0",
     "@aws-sdk/lib-dynamodb": "^3.1029.0",
     "better-sqlite3": "^12.9.0",
+    "express": "^4.17.2 || ^5.0.0",
     "ioredis": "^5.10.1",
     "mongodb": "^7.1.1",
     "mssql": "^12.2.1",
     "mysql2": "^3.14.4",
     "oracledb": "^6.10.0",
-    "pg": "^8.20.0"
+    "pg": "^8.20.0",
+    "ultimate-express": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "express": {
@@ -66,9 +65,6 @@
     "ultimate-express": {
       "optional": true
     },
-    "body-parser": {
-      "optional": true
-    },
     "@aws-sdk/client-dynamodb": {
       "optional": true
     },
@@ -98,7 +94,6 @@
     }
   },
   "devDependencies": {
-    "body-parser": "^1.20.0",
     "dotenv-cli": "^11.0.0",
     "express": "^4.21.0",
     "faker": "^5.5.3",

package/src/cli/commands/diff.js

@@ -0,0 +1,114 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseSchema } = require("../../schema/schema-parser");
+const { SchemaValidationError } = require("../../schema/schema-validator");
+const { schemaToModelMeta } = require("../../schema/schema-to-meta");
+const { computeDiff } = require("../diff-engine");
+
+/**
+ * Diff command handler for the unified CLI.
+ *
+ * Compares the current generated files against what the schema would produce,
+ * reporting additions, modifications (with line diffs), and deletions.
+ * Does NOT modify any files on disk.
+ *
+ * Supported flags:
+ *   --from      Path to schema file (default: dbmr.schema.json)
+ *   --json      Output JSON result via ctx
+ *
+ * @param {object} args - Parsed key-value args
+ * @param {object} flags - Universal flags: { yes, json, dryRun, noInstall, help }
+ * @param {import('../flags').OutputContext} ctx - Output context
+ */
+async function diff(args, flags, ctx) {
+  const schemaFile = args.from || "dbmr.schema.json";
+  const schemaPath = path.resolve(schemaFile);
+  const baseDir = process.cwd();
+
+  // --- 1. Read and parse schema ---
+  if (!fs.existsSync(schemaPath)) {
+    const msg = `Schema file not found: ${schemaFile}`;
+    if (flags.json) {
+      ctx.result({ error: true, code: "SCHEMA_NOT_FOUND", message: msg });
+    } else {
+      ctx.log(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  let schema;
+  try {
+    const raw = fs.readFileSync(schemaPath, "utf8");
+    schema = parseSchema(raw);
+  } catch (err) {
+    const msg = `Schema parse error: ${err.message}`;
+    if (flags.json) {
+      ctx.result({
+        error: true,
+        code: "SCHEMA_VALIDATION",
+        message: msg,
+        errors: err.errors || [],
+      });
+    } else {
+      ctx.log(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- 2. Compute diff ---
+  const meta = schemaToModelMeta(schema);
+  const relationships = schema.relationships || [];
+  const result = computeDiff(baseDir, meta, relationships);
+
+  // --- 3. Output results ---
+  if (flags.json) {
+    ctx.result({
+      added: result.added,
+      modified: result.modified,
+      deleted: result.deleted,
+    });
+  } else {
+    const total =
+      result.added.length + result.modified.length + result.deleted.length;
+
+    if (total === 0) {
+      ctx.log("All generated files are up to date.");
+      return;
+    }
+
+    if (result.added.length > 0) {
+      ctx.log("Added (new files to create):");
+      for (const f of result.added) {
+        ctx.log(`  + ${f}`);
+      }
+    }
+
+    if (result.modified.length > 0) {
+      ctx.log("Modified (files with changes):");
+      for (const m of result.modified) {
+        ctx.log(`  ~ ${m.file}`);
+        // Display line diffs indented
+        for (const line of m.diff.split("\n")) {
+          if (line) {
+            ctx.log(`    ${line}`);
+          }
+        }
+      }
+    }
+
+    if (result.deleted.length > 0) {
+      ctx.log("Deleted (extra files to remove):");
+      for (const f of result.deleted) {
+        ctx.log(`  - ${f}`);
+      }
+    }
+
+    ctx.log(`\n${total} file(s) differ.`);
+  }
+}
+
+module.exports = diff;