db-model-router 1.0.17 → 1.0.19

package/scripts/demo-create.js

@@ -1,87 +1,56 @@
-#!/usr/bin/env node
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const { execSync } = require("child_process");
-
-const ROOT = path.resolve(__dirname, "..");
-const DEMO = path.join(ROOT, "demo");
-
-const ADAPTER = process.argv[2] || "sqlite3";
-const SUPPORTED_ADAPTERS = ["sqlite3", "postgres", "mysql", "mariadb"];
-
-if (!SUPPORTED_ADAPTERS.includes(ADAPTER)) {
-  console.error(`Error: Unsupported adapter "${ADAPTER}".`);
-  console.error(`Supported: ${SUPPORTED_ADAPTERS.join(", ")}`);
-  process.exit(1);
-}
-
-// 1. Clear demo folder
-if (fs.existsSync(DEMO)) {
-  fs.rmSync(DEMO, { recursive: true, force: true });
-}
-fs.mkdirSync(DEMO, { recursive: true });
-
-const run = (cmd, cwd) => {
-  console.log(`\n> ${cmd}`);
-  execSync(cmd, { cwd, stdio: "inherit" });
-};
-
-if (ADAPTER === "postgres") {
-  // --- Postgres demo flow ---
-  const schemaPath = path.join(ROOT, "dbmr.postgres.test.schema.json");
-
-  // 2. Copy Postgres schema into the demo folder
-  const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
-  const schemaDest = path.join(DEMO, "dbmr.schema.json");
-  fs.writeFileSync(schemaDest, JSON.stringify(schema, null, 2) + "\n");
-  console.log(`\n> Copied ${schemaPath} → ${schemaDest}`);
-
-  // 3. Scaffold project with postgres
-  run(
-    "node ../src/cli/main.js init --database postgres --yes --no-install",
-    DEMO,
-  );
-
-  // 4. Generate from schema (already copied)
-  run("node ../src/cli/main.js generate --from dbmr.schema.json", DEMO);
-
-  // 5. Install dependencies
-  run("npm install", DEMO);
-
-  console.log("\n✔ Postgres demo project ready in ./demo");
-  console.log("cd demo && npm run migrate && npm run dev\n");
-} else {
-  // --- SQLite3 demo flow (default) ---
-
-  // 2. Scaffold project with sqlite3
-  run(
-    "node ../src/cli/main.js init --database sqlite3 --yes --no-install",
-    DEMO,
-  );
-
-  // 3. Copy schema and patch adapter to sqlite3
-  const schema = JSON.parse(
-    fs.readFileSync(path.join(ROOT, "dbmr.schema.json"), "utf8"),
-  );
-  schema.adapter = "sqlite3";
-  if (schema.options) {
-    delete schema.options.session;
-    delete schema.options.loki;
-  }
-  fs.writeFileSync(
-    path.join(DEMO, "dbmr.schema.json"),
-    JSON.stringify(schema, null, 2) + "\n",
-  );
-  console.log("\n> Copied and patched dbmr.schema.json (adapter → sqlite3)");
-
-  // 4. Generate models, routes, tests, openapi from schema
-  run("node ../src/cli/main.js generate --from dbmr.schema.json", DEMO);
-
-  // 5. Install dependencies
-  run("npm install", DEMO);
-
-  console.log("\n✔ Demo project ready in ./demo");
-  console.log("cd demo && npm run migrate && npm run dev\n");
-}
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const DEMO = path.join(ROOT, "demo");
+
+const ADAPTER = process.argv[2] || "sqlite3";
+const SUPPORTED_ADAPTERS = ["sqlite3", "postgres", "mysql", "mariadb"];
+
+if (!SUPPORTED_ADAPTERS.includes(ADAPTER)) {
+  console.error(`Error: Unsupported adapter "${ADAPTER}".`);
+  console.error(`Supported: ${SUPPORTED_ADAPTERS.join(", ")}`);
+  process.exit(1);
+}
+
+// 1. Clear demo folder
+if (fs.existsSync(DEMO)) {
+  fs.rmSync(DEMO, { recursive: true, force: true });
+}
+fs.mkdirSync(DEMO, { recursive: true });
+
+const run = (cmd, cwd) => {
+  console.log(`\n> ${cmd}`);
+  execSync(cmd, { cwd, stdio: "inherit" });
+};
+
+// 2. Copy schema into the demo folder
+const schemaPath =
+  ADAPTER === "postgres"
+    ? path.join(ROOT, "dbmr.postgres.test.schema.json")
+    : path.join(ROOT, "dbmr.schema.json");
+
+const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+
+// Patch adapter-specific options for the sqlite3 demo
+if (ADAPTER === "sqlite3") {
+  schema.adapter = "sqlite3";
+  if (schema.options) {
+    delete schema.options.session;
+    delete schema.options.loki;
+  }
+}
+
+const schemaDest = path.join(DEMO, "dbmr.schema.json");
+fs.writeFileSync(schemaDest, JSON.stringify(schema, null, 2) + "\n");
+console.log(`\n> Copied ${schemaPath} → ${schemaDest}`);
+
+// 3. Scaffold + generate from schema + install in one init run
+run("node ../src/cli/main.js init --yes", DEMO);
+
+console.log("\n✔ Demo project ready in ./demo");
+console.log("cd demo && npm run migrate && npm run dev\n");

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db-model-router
-description: Use this skill whenever the user wants to build a REST API with Node.js/Express backed by any database — including MySQL, PostgreSQL, SQLite, MongoDB, MSSQL, Oracle, Redis, DynamoDB, or CockroachDB. Trigger on any mention of db-model-router, or when the user asks to scaffold, generate, or wire up a CRUD API, models, or routes for a Node/Express backend. Also trigger when the user asks about connecting to a specific database with db-model-router, model definitions, filter syntax, bulk operations, schema-driven generation, or CLI commands like init/generate/inspect/doctor/diff.
+description: Use this skill whenever the user wants to build a REST API with Node.js/Express backed by any database — including MySQL, PostgreSQL, SQLite, MongoDB, MSSQL, Oracle, Redis, DynamoDB, or CockroachDB. Trigger on any mention of db-model-router, or when the user asks to scaffold, generate, or wire up a CRUD API, models, or routes for a Node/Express backend. Also trigger when the user asks about connecting to a specific database with db-model-router, model definitions, filter syntax, bulk operations, schema-driven generation, or CLI commands like init/inspect/doctor/diff/db-manager.
 ---
 
 # db-model-router — LLM Skill Reference
@@ -28,21 +28,21 @@ MySQL/MariaDB use `mysql2` — no separate reference file needed (see Connection
 
 ## LLM Workflow (follow this order for new projects)
 
-1. **Scaffold**: `db-model-router init --framework express --database postgres --session redis --rateLimiting --helmet --logger --yes`
-2. **Start infra**: `npm run docker:up`
-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. **Generate SaaS structure** (if multi-tenant): `db-model-router generate --from dbmr.schema.json --saas-structure`
-7. **Run**: `npm run dev`
+1. **Write `dbmr.schema.json`** — adapter, framework, `options` (session, rateLimiting, helmet, logger, loki, output, saasStructure, apiBasePath, port), `tables`, `relationships`.
+2. **Build the whole project (first buildout only)**: `db-model-router init` (reads `./dbmr.schema.json` → app.js + models + routes + migrations + tests + OpenAPI + optional SaaS). Add `--no-install` to skip npm install, `--dry-run` to preview.
+3. **Start infra**: `npm run docker:up`
+4. **Migrate**: `npm run migrate`
+5. **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.
+> `init` is **first-buildout only**. It refuses to run if `app.js` already exists in cwd. To add new tables/models/routes after buildout, do it manually — add a migration (`node commons/add_migration.js <name>`), add `models/<table>.js`, mount `routes/<table>/index.js` in `routes/index.js`. See `db-model-router help init`.
+> When `options.saasStructure` is `true` (default), 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:
+For existing databases, use `inspect` first, then `init`:
 
 ```bash
 db-model-router inspect --type postgres --env .env   # → writes dbmr.schema.json
-db-model-router generate --from dbmr.schema.json      # → models, routes, tests, OpenAPI
+# edit dbmr.schema.json (set options, parents, etc.) then:
+db-model-router init                                  # → full project from schema
 ```
 
 ---
@@ -252,56 +252,61 @@ db-model-router <command> [options]
 db-model-router help <command>
 ```
 
-### `init` — Scaffold project
+### `init` — First-buildout-only project scaffold
 
 ```bash
-# Fully non-interactive (LLM-friendly)
-db-model-router init --framework express --database postgres --session redis \
-  --rateLimiting --helmet --logger --yes
+# Build the full project from ./dbmr.schema.json (first buildout only)
+db-model-router init
 
-# With Loki/Grafana logging
-db-model-router init --database postgres --logger --loki --yes
+# Specific schema path
+db-model-router init ./my.schema.json
 
-# From schema file
-db-model-router init --from dbmr.schema.json --yes --no-install
+# Preview / skip install
+db-model-router init --dry-run
+db-model-router init --no-install
 ```
 
-Key flags: `--framework`, `--database` (or `--db`), `--session`, `--output`, `--rateLimiting`, `--helmet`, `--logger`, `--loki`, `--yes`, `--no-install`
+**First buildout only** — refuses if `app.js` already exists in cwd. No config flags; all config lives in `options` of `dbmr.schema.json`:
+
+| Option           | Default     | Description                                                                 |
+| --------------- | ----------- | --------------------------------------------------------------------------- |
+| `output`        | `null` (cwd)| Directory for backend source files (package.json/app.js stay in root)      |
+| `saasStructure` | `true`      | Generate the multi-tenant SaaS backend (tables, middleware, routes, seeds)|
+| `apiBasePath`   | `"/api"`    | API mount path (→ `.env` `API_BASE_PATH`)                                  |
+| `port`          | `3000`      | Server port (→ `.env` `PORT`)                                              |
+| `session`       | `"memory"`  | `memory` / `redis` / `database`                                             |
+| `rateLimiting`  | `true`      | Enable `express-rate-limit`                                                 |
+| `helmet`        | `true`      | Enable Helmet security headers                                              |
+| `logger`        | `true`      | Enable Winston request logger                                               |
+| `loki`          | `false`     | Enable Grafana Loki transport + Loki/Grafana in docker-compose              |
 
 Generated structure (ESM, `"type":"module"`):
 
 ```
 app.js                             Express entry point
-.env / .env.example                Env config (random passwords)
+.env / .env.example                Env config (PORT, API_BASE_PATH, random passwords)
 docker-compose.yml                 DB + optional Loki/Grafana
 <output>/commons/db.js             Database init + global.db
-<output>/commons/migrate.js        Migration runner
-<output>/route/index.js            Central route mounting
-<output>/route/health.js           GET /health endpoint
-<output>/migrations/               Initial migration files
+<output>/commons/migrate.js         Migration runner
+<output>/commons/add_migration.js   Migration creator helper
+<output>/routes/index.js            Central route mounting (SaaS + product routes)
+<output>/routes/health.js           GET /health endpoint
+<output>/routes/docs.js             Swagger UI at /docs
+<output>/routes/<table>/index.js    CRUD route per table (nested by parent)
+<output>/models/<table>.js          Model per table
+<output>/migrations/                CREATE TABLE migrations
+<output>/test/<table>.test.js       CRUD endpoint tests
+<output>/openapi.json               OpenAPI 3.0 spec
+<output>/seeds/saas-seed.js         (when saasStructure=true)
 ```
 
-Docker services auto-generated: database, Redis (if session=redis), Loki + Grafana (if --loki).
+Docker services auto-generated: database, Redis (if session=redis), Loki + Grafana (if options.loki).
 
 Scripts: `start`, `dev`, `test`, `migrate`, `add_migration`, `docker:build`, `docker:up`, `docker:down`.
 
-### `inspect` — Introspect existing DB → schema
-
-```bash
-db-model-router inspect --type postgres --env .env [--out schema.json] [--tables t1,t2]
-```
-
-### `generate` — Generate code from schema
-
-```bash
-db-model-router generate --from dbmr.schema.json [--output <dir>] [--models=false] [--routes=false] [--openapi=false] [--tests=false] [--migrations=false] [--saas-structure=false]
-```
+#### `options.saasStructure` (default: enabled)
 
-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:
+SaaS structure is generated unless `options.saasStructure` is `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`
@@ -310,10 +315,31 @@ SaaS structure is always generated unless explicitly disabled with `--saas-struc
 - **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`).
+> **Critical**: Since `saasStructure` defaults to `true`, `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.
 
+#### Adding tables/models/routes after buildout (manual — do NOT re-run `init`)
+
+1. **Migration**: `node commons/add_migration.js <name>` → write `CREATE TABLE` (SQL) or `create_<table>.js` (NoSQL) inside the new timestamped file.
+2. **Model**: add `models/<table>.js` mirroring an existing model:
+   ```js
+   const model = require('#commons/model');
+   const db = require('#commons/db');
+   module.exports = model(db, '<table>', structure, '<pk>', uniqueKeys, option);
+   ```
+3. **Route**: add `routes/<table>/index.js` via `route(model)`, then mount in `routes/index.js`:
+   ```js
+   router.use('/<endpoint>', require('./<table>/index.js'));
+   ```
+4. Run the new migration, then restart the server.
+
+### `inspect` — Introspect existing DB → schema
+
+```bash
+db-model-router inspect --type postgres --env .env [--out schema.json] [--tables t1,t2]
+```
+
 ### `doctor` — Validate schema + check file sync
 
 ```bash
@@ -326,7 +352,7 @@ db-model-router doctor [--from dbmr.schema.json] [--json]
 db-model-router diff [--from dbmr.schema.json] [--json]
 ```
 
-Universal flags (all commands): `--yes`, `--json`, `--dry-run`, `--no-install`, `--help`
+Universal flags (all commands): `--json`, `--dry-run`, `--no-install`, `--help`
 
 ### `db-manager` — Launch database management UI
 
@@ -357,7 +383,12 @@ Requires a `.env` file with `DB_TYPE` and connection variables.
     "session": "redis",
     "rateLimiting": true,
     "helmet": true,
-    "logger": true
+    "logger": true,
+    "loki": false,
+    "output": null,
+    "saasStructure": true,
+    "apiBasePath": "/api",
+    "port": 3000
   },
   "tables": {
     "users": {
@@ -644,6 +675,6 @@ Topic: `{KAFKA_TOPIC_PREFIX}.{table_name}` (e.g. `dbmr.users`)
 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.
+15. When `options.saasStructure` is `true` (default), 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. `init` is first-buildout only (refuses if `app.js` exists) — add new tables/models/routes manually (migration + model + route mount in `routes/index.js`).
 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.
 17. `search` is a **reserved** query param — never a column filter. It only takes effect when the model has `option.search_columns` set (config-only). It OR-joins a `LIKE %term%` across those columns and AND-combines with other filters. Works on `find`/`findOne`/`list` and the `GET /:id` + `GET /` routes.

package/src/cli/commands/generate.js

@@ -2,7 +2,6 @@
 
 const fs = require("fs");
 const path = require("path");
-const { parseSchema } = require("../../schema/schema-parser");
 const { schemaToModelMeta } = require("../../schema/schema-to-meta");
 const { generateModelFile } = require("../generate-model");
 const {
@@ -27,6 +26,7 @@ const { generateSaasOpenAPIPaths } = require("../saas/generate-saas-openapi");
 const SUPPORTED_ADAPTERS = [
   "postgres",
   "mysql",
+  "mariadb",
   "sqlite3",
   "mssql",
   "oracle",
@@ -37,64 +37,23 @@ const SUPPORTED_ADAPTERS = [
 ];
 
 /**
- * Generate command handler for the unified CLI.
+ * Build all schema-driven artifacts (models, routes, tests, OpenAPI spec,
+ * migrations, docs route, and optional SaaS structure) from an already-parsed
+ * schema, writing them under `baseDir`.
  *
- * Reads a schema file, converts to ModelMeta[], and generates
- * models, routes, tests, OpenAPI spec, migrations, and docs route.
+ * This is the internal buildout engine invoked by the `init` command. It is
+ * NOT registered as a CLI subcommand. All artifact types are always generated;
+ * the SaaS structure is gated by `schema.options.saasStructure` (default true).
  *
- * 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 + docs route
- *   --tests       Generate only test files
- *   --migrations  Generate only migration files
- *   --dry-run     Report planned files without writing
- *   --json        Output JSON result via ctx
- *
- * When no artifact flags are provided, all artifact types are generated.
- *
- * @param {object} args - Parsed key-value args
- * @param {object} flags - Universal flags: { yes, json, dryRun, noInstall, help }
- * @param {import('../flags').OutputContext} ctx - Output context
+ * @param {object} opts
+ * @param {object} opts.schema - Parsed schema from parseSchema()
+ * @param {string} opts.baseDir - Absolute directory to write artifacts into
+ * @param {import('../flags').OutputContext} opts.ctx - Output context for --json support
+ * @param {object} opts.flags - Universal flags: { json, dryRun, ... }
+ * @returns {Promise<{ files: Array<{ path: string, status: string }> }>}
  */
-async function generate(args, flags, ctx) {
-  // --- Standard schema-based generation ---
-  const schemaPath = path.resolve(args.from || "dbmr.schema.json");
-
-  if (!fs.existsSync(schemaPath)) {
-    const msg = `Schema file not found: ${args.from || "dbmr.schema.json"}`;
-    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;
-  }
-
+async function buildSchemaArtifacts({ schema, baseDir, ctx, flags }) {
   const meta = schemaToModelMeta(schema);
-  const relationships = schema.relationships || [];
   const tableNames = meta.map((m) => m.table).sort();
 
   // For route generation, only use parent-derived relationships.
@@ -126,37 +85,13 @@ async function generate(args, flags, ctx) {
     ancestors[m.table] = chain;
   }
 
-  // Determine which artifact types to generate.
-  // If any specific artifact flag is explicitly set to true, only generate those.
-  // Otherwise, all artifact types are generated (unless explicitly set to false).
-  const hasExplicitTrue =
-    args.models === true ||
-    args.routes === true ||
-    args.openapi === true ||
-    args.tests === true ||
-    args.migrations === true;
-
-  let genModels, genRoutes, genOpenapi, genTests, genMigrations, genSaas;
-
-  if (hasExplicitTrue) {
-    // Selective mode: only generate what was explicitly requested
-    genModels = args.models === true;
-    genRoutes = args.routes === true;
-    genOpenapi = args.openapi === true;
-    genTests = args.tests === true;
-    genMigrations = args.migrations === true;
-    genSaas = args["saas-structure"] === true;
-  } else {
-    // Default mode: generate all unless explicitly disabled
-    genModels = args.models !== false;
-    genRoutes = args.routes !== false;
-    genOpenapi = args.openapi !== false;
-    genTests = args.tests !== false;
-    genMigrations = args.migrations !== false;
-    genSaas = args["saas-structure"] !== false;
-  }
-
-  const baseDir = path.resolve(args.output || process.cwd());
+  // Always generate every artifact type. SaaS gated by schema.options.saasStructure.
+  const genModels = true;
+  const genRoutes = true;
+  const genOpenapi = true;
+  const genTests = true;
+  const genMigrations = true;
+  const genSaas = !(schema.options && schema.options.saasStructure === false);
 
   // Collect all planned files: { relPath, content }
   const planned = [];
@@ -179,9 +114,6 @@ async function generate(args, flags, ctx) {
       childrenByParent[rel.parent].push(rel);
     }
 
-    // Generate exactly ONE route file per table at its correct nested path.
-    // Intermediate tables (both child and parent) get a hybrid route file
-    // that scopes their own CRUD by an ancestor FK and mounts their children.
     for (const m of meta) {
       const tableName = m.table;
       const chain = ancestors[tableName];
@@ -194,7 +126,6 @@ async function generate(args, flags, ctx) {
       if (hasChildren) {
         const children = childrenByParent[tableName];
         if (hasParent) {
-          // Intermediate node: own CRUD scoped by parent PK + mounts children
           const immediateParent = chain[chain.length - 1];
           const parentFk = schema.tables[immediateParent].pk;
           planned.push({
@@ -202,14 +133,12 @@ async function generate(args, flags, ctx) {
             content: generateParentRouteFile(tableName, children, parentFk),
           });
         } else {
-          // Root parent: own CRUD unscoped + mounts children
           planned.push({
             relPath,
             content: generateParentRouteFile(tableName, children),
           });
         }
       } else if (hasParent) {
-        // Leaf child
         const immediateParent = chain[chain.length - 1];
         const parentFk = schema.tables[immediateParent].pk;
         planned.push({
@@ -217,7 +146,6 @@ async function generate(args, flags, ctx) {
           content: generateChildRouteFile(tableName, immediateParent, parentFk),
         });
       } else {
-        // Root leaf
         planned.push({
           relPath,
           content: generateRouteFile(tableName),
@@ -225,7 +153,6 @@ async function generate(args, flags, ctx) {
       }
     }
 
-    // Routes index file (include docs route when openapi is being generated)
     planned.push({
       relPath: "routes/index.js",
       content: generateRoutesIndexFile(tableNames, routeRelationships, {
@@ -238,19 +165,12 @@ async function generate(args, flags, ctx) {
   if (genOpenapi) {
     const spec = generateOpenAPISpec(meta, { relationships: routeRelationships });
 
-    // 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 = {};
       }
@@ -261,8 +181,6 @@ async function generate(args, flags, ctx) {
       relPath: "openapi.json",
       content: JSON.stringify(spec, null, 2) + "\n",
     });
-
-    // Generate Swagger UI docs route
     planned.push({
       relPath: "routes/docs.js",
       content: generateDocsRoute(),
@@ -315,20 +233,19 @@ async function generate(args, flags, ctx) {
 
   // --- 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;
+    const 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.`;
+        : `Adapter is required for saas-structure generation. 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;
+      return { files: [] };
     }
 
     const saasFiles = generateSaasStructure(adapter, {
@@ -342,8 +259,8 @@ async function generate(args, flags, ctx) {
     });
 
     // 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.
+    // 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",
     );
@@ -384,25 +301,23 @@ async function generate(args, flags, ctx) {
         ctx.log(`  unchanged ${relPath}`);
         continue;
       }
-      // File exists but content differs — overwrite
       fs.mkdirSync(path.dirname(fullPath), { recursive: true });
       fs.writeFileSync(fullPath, content, "utf8");
       results.push({ path: relPath, status: "overwritten" });
       ctx.log(`  overwritten ${relPath}`);
     } else {
-      // File does not exist — create
       fs.mkdirSync(path.dirname(fullPath), { recursive: true });
       fs.writeFileSync(fullPath, content, "utf8");
       results.push({ path: relPath, status: "created" });
       ctx.log(`  created ${relPath}`);
     }
   }
-  // --- Output ---
+
   if (flags.dryRun) {
     if (flags.json) {
       ctx.result({ files: results });
     } else {
-      ctx.log("Dry run — the following files would be generated:");
+      ctx.log("Dry run — the following schema artifacts would be generated:");
       for (const r of results) {
         ctx.log(`  ${r.path}`);
       }
@@ -417,9 +332,11 @@ async function generate(args, flags, ctx) {
     ).length;
     const unchanged = results.filter((r) => r.status === "unchanged").length;
     ctx.log(
-      `\nDone. ${created} created, ${overwritten} overwritten, ${unchanged} unchanged.`,
+      `\nSchema artifacts: ${created} created, ${overwritten} overwritten, ${unchanged} unchanged.`,
     );
   }
+
+  return { files: results };
 }
 
-module.exports = generate;
+module.exports = { buildSchemaArtifacts, SUPPORTED_ADAPTERS };