db-model-router 1.0.5 → 1.0.7

package/skill/SKILL.md

@@ -33,7 +33,10 @@ MySQL/MariaDB use `mysql2` — no separate reference file needed (see Connection
 3. **Migrations**: Write SQL/JS files into `migrations/`, then `npm run migrate`
 4. **Generate models**: `db-model-router generate --from dbmr.schema.json --models`
 5. **Generate routes + tests**: `db-model-router generate --from dbmr.schema.json --routes --tests`
-6. **Run**: `npm run dev`
+6. **Generate SaaS structure** (if multi-tenant): `db-model-router generate --from dbmr.schema.json --saas-structure`
+7. **Run**: `npm run dev`
+
+> When using `--saas-structure`, skip defining `users`, `tenants`, `roles`, `role_permissions` in your schema — they're auto-generated with auth middleware, permission system, and tenant isolation.
 
 For existing databases, use `inspect` first:
 
@@ -267,10 +270,25 @@ db-model-router inspect --type postgres --env .env [--out schema.json] [--tables
 ### `generate` — Generate code from schema
 
 ```bash
-db-model-router generate --from dbmr.schema.json [--models] [--routes] [--openapi] [--tests] [--llm-docs]
+db-model-router generate --from dbmr.schema.json [--models=false] [--routes=false] [--openapi=false] [--tests=false] [--migrations=false] [--saas-structure=false]
 ```
 
-No flags = generate all.
+All artifact types are **enabled by default**. Use `--flag=false` to disable specific ones.
+
+#### `--saas-structure` (default: enabled)
+
+SaaS structure is always generated unless explicitly disabled with `--saas-structure=false`. It produces a complete multi-tenant SaaS backend on top of schema-generated code:
+
+- **Tables**: `tenants`, `users`, `roles`, `role_permissions`, `webhooks`, `webhook_logs`
+- **Middleware**: `authenticate.js`, `tenantIsolation.js`, `hasPermission.js`
+- **Routes**: CRUD for users/tenants/roles/permissions + auth (login/logout)
+- **Utilities**: `commons/password.js` (scrypt), `commons/modules.js`, `commons/webhook.js`
+- **Seeds**: Super Admin (all permissions, global scope) + Tenant Admin role template
+- **Migrations**: Single consolidated `.sql` file with all SaaS tables
+
+> **Critical**: Since `--saas-structure` is on by default, `users`, `tenants`, `roles`, and `role_permissions` are already generated. **Do NOT add these tables to `dbmr.schema.json`** — only define your product/domain tables (e.g., `products`, `orders`, `invoices`).
+
+The generated `routes/index.js` combines SaaS routes (`/api/auth`, `/api/users`, `/api/tenants`, `/api/roles`, `/api/roles/:role_id/permissions`) with schema-generated product routes. Swagger docs include all SaaS endpoints first, then product endpoints.
 
 ### `doctor` — Validate schema + check file sync
 
@@ -286,6 +304,23 @@ db-model-router diff [--from dbmr.schema.json] [--json]
 
 Universal flags (all commands): `--yes`, `--json`, `--dry-run`, `--no-install`, `--help`
 
+### `db-manager` — Launch database management UI
+
+```bash
+db-model-router db-manager [--env .env] [--port 4000]
+```
+
+Starts a built-in web dashboard for browsing and managing your database. Features:
+
+- Table browser with filtering, sorting, pagination, inline editing
+- Raw SQL query editor with CSV export
+- Query history tracking
+- Dashboard overview (table stats: columns, indexes, rows, size)
+- Light / Dark / System theme modes (persisted via localStorage)
+- Typography: Fira Sans (UI) + Fira Code (data/code)
+
+Requires a `.env` file with `DB_TYPE` and connection variables.
+
 ---
 
 ## Schema-Driven Workflow (dbmr.schema.json)
@@ -446,6 +481,85 @@ When `logger=true`: adds `APP_NAME LOG_LEVEL LOKI_HOST`.
 
 ---
 
+## Kafka Event Production
+
+Built-in Kafka support. When `KAFKA_BROKER` env var is set, every write operation automatically produces a Kafka event per affected row.
+
+### Install & Configure
+
+```bash
+npm install kafkajs
+```
+
+```env
+KAFKA_BROKER=localhost:9092
+KAFKA_CLIENT_ID=my-app
+KAFKA_TOPIC_PREFIX=dbmr
+```
+
+### Initialize
+
+```js
+import dbModelRouter from "db-model-router";
+const { init, db, kafka } = dbModelRouter;
+
+init("postgres");
+db.connect({ host: "localhost", database: "my_app" });
+
+// Connect Kafka producer
+await kafka.init();
+// Or with explicit options:
+await kafka.init({
+  broker: "localhost:9092",
+  clientId: "my-app",
+  topicPrefix: "dbmr",
+});
+```
+
+### kafka API
+
+| Method                                  | Description                                  |
+| --------------------------------------- | -------------------------------------------- |
+| `kafka.init(opts?)`                     | Connect producer. Returns `true` on success. |
+| `kafka.disconnect()`                    | Graceful shutdown.                           |
+| `kafka.produce(table, operation, data)` | Manually produce event(s).                   |
+| `kafka.status()`                        | Returns `true` if connected.                 |
+
+### Event Format
+
+Topic: `{KAFKA_TOPIC_PREFIX}.{table_name}` (e.g. `dbmr.users`)
+
+```json
+{
+  "table_name": "users",
+  "operation_type": "insert",
+  "data": { "id": 1, "name": "Alice", "email": "alice@example.com" },
+  "timestamp": "2026-05-09T12:00:00.000Z"
+}
+```
+
+- `operation_type`: `"insert"` | `"update"` | `"upsert"` | `"delete"`
+- `data`: Single object (one event per affected row)
+- Bulk ops (e.g. 1000 inserts) → 1000 events, batched in chunks of 500
+
+### Rules
+
+- No `KAFKA_BROKER` → Kafka fully disabled, zero overhead
+- Events fire after successful DB write only
+- Read ops (`find`, `list`, `byId`, `findOne`) never produce events
+- Failed produce logs warning, does not throw or affect API response
+- `kafkajs` is an optional peer dependency — only required when `KAFKA_BROKER` is set
+
+### Environment Variables
+
+| Variable             | Default              | Description                 |
+| -------------------- | -------------------- | --------------------------- |
+| `KAFKA_BROKER`       | _(unset = disabled)_ | Comma-separated broker URLs |
+| `KAFKA_CLIENT_ID`    | `db-model-router`    | Kafka client identifier     |
+| `KAFKA_TOPIC_PREFIX` | `dbmr`               | Topic prefix                |
+
+---
+
 ## Rules
 
 1. `init()` before `db.connect()`. Don't destructure `db` before `init()` — it's a getter.
@@ -462,3 +576,5 @@ When `logger=true`: adds `APP_NAME LOG_LEVEL LOKI_HOST`.
 12. Docker passwords are randomly generated and shared between `.env` and `docker-compose.yml`.
 13. PK convention: `<table>_id` (e.g. `user_id`, `post_id`). Include ALL columns in schema.
 14. Use `parent` only for domain hierarchies (e.g. `posts → comments`), not system tables.
+15. When `--saas-structure` is active, do NOT define `users`, `tenants`, `roles`, or `role_permissions` in `dbmr.schema.json` — they are already generated with models, routes, middleware, and migrations. Only add your product-specific tables to the schema.
+16. Kafka is opt-in via `KAFKA_BROKER` env var. Call `kafka.init()` after `db.connect()`. Each write op produces one event per row to `{prefix}.{table}` topic.

package/src/cli/commands/db-manager.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * DB Manager command handler for the unified CLI.
+ *
+ * Starts a live Express-based database management UI that connects
+ * to any supported database through the library's adapter layer.
+ *
+ * Supported flags:
+ *   --env   Path to .env file (default: ".env" in cwd)
+ *   --port  Server port (default: 4000)
+ *
+ * @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 dbManager(args, flags, ctx) {
+  // Parse flags with defaults
+  const envPath = path.resolve(args.env || ".env");
+  const port = parseInt(args.port, 10) || 4000;
+
+  // Validate env file exists
+  if (!fs.existsSync(envPath)) {
+    ctx.log(`Error: Environment file not found: ${envPath}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Load env vars from the specified file
+  require("dotenv").config({ path: envPath });
+
+  // Validate DB_TYPE is present
+  const dbType = process.env.DB_TYPE;
+  if (!dbType) {
+    ctx.log(`Error: DB_TYPE not specified in ${envPath}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Initialize the library adapter
+  const restRouter = require("../../index.js");
+  try {
+    restRouter.init(dbType);
+  } catch (err) {
+    ctx.log(`Error: Failed to connect to ${dbType} database: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = restRouter.db;
+
+  // Build connection config based on database type
+  const config = { dateStrings: true };
+
+  switch (dbType) {
+    case "sqlite3":
+      config.database = process.env.DB_NAME;
+      config.filename = process.env.DB_NAME;
+      break;
+    case "mssql":
+      config.server = process.env.DB_HOST || "localhost";
+      config.port = process.env.DB_PORT;
+      config.database = process.env.DB_NAME;
+      config.user = process.env.DB_USER;
+      config.password = process.env.DB_PASS;
+      config.options = { encrypt: false, trustServerCertificate: true };
+      break;
+    default:
+      // mysql, postgres, cockroachdb, etc.
+      config.host = process.env.DB_HOST || "localhost";
+      config.port = process.env.DB_PORT;
+      config.database = process.env.DB_NAME;
+      config.user = process.env.DB_USER;
+      config.password = process.env.DB_PASS;
+      break;
+  }
+
+  // Connect to the target database
+  try {
+    db.connect(config);
+  } catch (err) {
+    ctx.log(`Error: Failed to connect to ${dbType} database: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Initialize metadata DB
+  const createMetadataDb = require("../../../db-manager/metadata-db.js");
+  const metaDbPath = path.join(
+    __dirname,
+    "../../../db-manager/.dbmanager.sqlite",
+  );
+  const metaDb = createMetadataDb(metaDbPath);
+  metaDb.init();
+
+  // Record connection in history
+  metaDb.recordConnection(
+    dbType,
+    process.env.DB_HOST || null,
+    process.env.DB_NAME || dbType,
+  );
+
+  // Create Express app
+  const createApp = require("../../../db-manager/server.js");
+  const app = createApp(db, metaDb, dbType);
+
+  // Start server
+  const server = app.listen(port, () => {
+    ctx.log(`DB Manager running at http://localhost:${port}`);
+  });
+
+  // Graceful shutdown handler
+  const shutdown = () => {
+    server.close(() => {
+      try {
+        if (db.disconnect) {
+          db.disconnect();
+        }
+      } catch (_) {
+        // ignore disconnect errors
+      }
+      metaDb.close();
+      process.exit(0);
+    });
+  };
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+module.exports = dbManager;

package/src/cli/commands/generate.js

@@ -7,16 +7,34 @@ const { schemaToModelMeta } = require("../../schema/schema-to-meta");
 const { generateModelFile } = require("../generate-model");
 const {
   generateRouteFile,
+  generateParentRouteFile,
   generateChildRouteFile,
   generateRoutesIndexFile,
   generateTestFile,
   generateChildTestFile,
 } = 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");
+const { generateSaasStructure } = require("../generate-saas-structure");
+const { generateSaasOpenAPIPaths } = require("../saas/generate-saas-openapi");
+
+/**
+ * Supported database adapters for the SaaS structure generator.
+ * @type {string[]}
+ */
+const SUPPORTED_ADAPTERS = [
+  "postgres",
+  "mysql",
+  "sqlite3",
+  "mssql",
+  "oracle",
+  "cockroachdb",
+  "mongodb",
+  "dynamodb",
+  "redis",
+];
 
 /**
  * Generate command handler for the unified CLI.
@@ -31,7 +49,6 @@ const { migrationTimestamp } = require("../init/generators");
  *   --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
  *
@@ -42,6 +59,7 @@ const { migrationTimestamp } = require("../init/generators");
  * @param {import('../flags').OutputContext} ctx - Output context
  */
 async function generate(args, flags, ctx) {
+  // --- Standard schema-based generation ---
   const schemaPath = path.resolve(args.from || "dbmr.schema.json");
 
   if (!fs.existsSync(schemaPath)) {
@@ -80,22 +98,14 @@ async function generate(args, flags, ctx) {
   const tableNames = meta.map((m) => m.table).sort();
 
   // Determine which artifact types to generate
-  const hasArtifactFlag =
-    args.models === true ||
-    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";
+  // All flags default to true — use --flag=false to disable
+  const genModels = args.models !== false;
+  const genRoutes = args.routes !== false;
+  const genOpenapi = args.openapi !== false;
+  const genTests = args.tests !== false;
+  const genMigrations = args.migrations !== false;
+  const genSaas = args["saas-structure"] !== false;
+
   const baseDir = process.cwd();
 
   // Collect all planned files: { relPath, content }
@@ -113,31 +123,40 @@ async function generate(args, flags, ctx) {
 
   // --- Route files ---
   if (genRoutes) {
-    // Collect child tables to skip generating top-level route files for them
+    // Collect child tables and group by parent
     const nestedChildren = new Set();
+    const childrenByParent = {};
     for (const rel of relationships) {
       nestedChildren.add(rel.child);
+      if (!childrenByParent[rel.parent]) childrenByParent[rel.parent] = [];
+      childrenByParent[rel.parent].push(rel);
     }
 
-    // One route per top-level table (skip children)
+    // Generate route files for each table
     for (const m of meta) {
       if (nestedChildren.has(m.table)) continue;
-      planned.push({
-        relPath: `routes/${m.table}.js`,
-        content: generateRouteFile(m.table, modelsRelPath),
-      });
+
+      const children = childrenByParent[m.table] || [];
+      if (children.length > 0) {
+        // Parent with children: generates index.js that mounts child routes
+        planned.push({
+          relPath: `routes/${m.table}/index.js`,
+          content: generateParentRouteFile(m.table, children),
+        });
+      } else {
+        // Simple table: just CRUD
+        planned.push({
+          relPath: `routes/${m.table}/index.js`,
+          content: generateRouteFile(m.table),
+        });
+      }
     }
 
-    // Child route files in subfolders: routes/<parent>/<child>.js
+    // Child route files inside parent folders: routes/<parent>/<child>/index.js
     for (const rel of relationships) {
       planned.push({
-        relPath: `routes/${rel.parent}/${rel.child}.js`,
-        content: generateChildRouteFile(
-          rel.child,
-          rel.parent,
-          rel.foreignKey,
-          `../../models`,
-        ),
+        relPath: `routes/${rel.parent}/${rel.child}/index.js`,
+        content: generateChildRouteFile(rel.child, rel.parent, rel.foreignKey),
       });
     }
 
@@ -152,9 +171,30 @@ async function generate(args, flags, ctx) {
 
   // --- OpenAPI spec + docs route ---
   if (genOpenapi) {
+    const spec = generateOpenAPISpec(meta, { relationships });
+
+    // Merge SaaS routes into the OpenAPI spec when saas-structure is active
+    // SaaS routes appear BEFORE product routes in the docs
+    if (genSaas) {
+      const saasApi = generateSaasOpenAPIPaths();
+
+      // Prepend SaaS paths before product paths
+      const productPaths = spec.paths;
+      spec.paths = { ...saasApi.paths, ...productPaths };
+
+      // Prepend SaaS schemas before product schemas
+      const productSchemas = spec.components.schemas;
+      spec.components.schemas = { ...saasApi.schemas, ...productSchemas };
+
+      if (!spec.components.securitySchemes) {
+        spec.components.securitySchemes = {};
+      }
+      Object.assign(spec.components.securitySchemes, saasApi.securitySchemes);
+    }
+
     planned.push({
       relPath: "openapi.json",
-      content: JSON.stringify(generateOpenAPISpec(meta), null, 2) + "\n",
+      content: JSON.stringify(spec, null, 2) + "\n",
     });
 
     // Generate Swagger UI docs route
@@ -208,16 +248,46 @@ async function generate(args, flags, ctx) {
     }
   }
 
-  // --- LLM docs ---
-  if (genLlmDocs) {
-    planned.push({
-      relPath: "llms.txt",
-      content: generateLlmsTxt(),
-    });
-    planned.push({
-      relPath: "docs/llm.md",
-      content: generateLlmMd(),
+  // --- SaaS structure files (additive, on top of schema-based generation) ---
+  if (genSaas) {
+    // Determine adapter: from --adapter flag, or from the schema's adapter field
+    const adapter = args.adapter || schema.adapter;
+
+    if (!adapter || !SUPPORTED_ADAPTERS.includes(adapter)) {
+      const msg = adapter
+        ? `Invalid adapter: ${adapter}. Supported: ${SUPPORTED_ADAPTERS.join(", ")}`
+        : `Adapter is required for saas-structure generation. Provide --adapter or set adapter in schema.`;
+      if (flags.json) {
+        ctx.result({ error: true, code: "INVALID_ADAPTER", message: msg });
+      } else {
+        ctx.log(`Error: ${msg}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const saasFiles = generateSaasStructure(adapter, {
+      dryRun: flags.dryRun,
+      json: flags.json,
+      timestamp: new Date(),
+      tableNames,
+      relationships,
+      routeOptions: { includeDocs: genOpenapi },
     });
+
+    // The SaaS generator produces a combined routes/index.js that includes
+    // both SaaS routes and dbmr schema-generated routes. Remove any
+    // previously-planned routes/index.js from the schema generator.
+    const existingIndexIdx = planned.findIndex(
+      (p) => p.relPath === "routes/index.js",
+    );
+    if (existingIndexIdx !== -1) {
+      planned.splice(existingIndexIdx, 1);
+    }
+
+    for (const entry of saasFiles) {
+      planned.push(entry);
+    }
   }
 
   // --- Process planned files ---
@@ -252,7 +322,6 @@ async function generate(args, flags, ctx) {
       ctx.log(`  created ${relPath}`);
     }
   }
-
   // --- Output ---
   if (flags.dryRun) {
     if (flags.json) {

package/src/cli/commands/help.js

@@ -82,7 +82,6 @@ Options:
   --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

package/src/cli/diff-engine.js

@@ -117,7 +117,8 @@ function buildExpectedFiles(meta, relationships) {
   // OpenAPI spec
   expected.set(
     "openapi.json",
-    JSON.stringify(generateOpenAPISpec(meta), null, 2) + "\n",
+    JSON.stringify(generateOpenAPISpec(meta, { relationships }), null, 2) +
+      "\n",
   );
 
   return expected;

package/src/cli/generate-model.js

@@ -544,7 +544,9 @@ function generateModelFile(m) {
     if (opt.modified_at) parts.push(`modified_at: "${opt.modified_at}"`);
     optionStr = `\n  { ${parts.join(", ")} },`;
   }
-  return `const { db, model } = require("db-model-router");
+  return `import dbModelRouter from "db-model-router";
+
+const { db, model } = dbModelRouter;
 
 const ${varName} = model(
   db,
@@ -554,7 +556,7 @@ const ${varName} = model(
   ${uniqueStr},${optionStr}
 );
 
-module.exports = ${varName};
+export default ${varName};
 `;
 }
 
@@ -563,11 +565,14 @@ function generateIndexFile(models) {
   let exports = "";
   for (const m of models) {
     const varName = safeVarName(m.table);
-    imports += `const ${varName} = require("./${m.table}");\n`;
+    imports += `import ${varName} from "./${m.table}.js";\n`;
     exports += `  ${varName},\n`;
   }
   return `${imports}
-module.exports = {
+export {
+${exports}};
+
+export default {
 ${exports}};
 `;
 }