db-model-router 1.0.2 → 1.0.4

package/src/cli/commands/generate.js

@@ -0,0 +1,240 @@
+"use strict";
+
+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 {
+  generateRouteFile,
+  generateChildRouteFile,
+  generateRoutesIndexFile,
+  generateTestFile,
+  generateChildTestFile,
+} = require("../generate-route");
+const { generateOpenAPISpec } = require("../generate-openapi");
+const { generateLlmsTxt, generateLlmMd } = require("./generate-llm-docs");
+
+/**
+ * Generate command handler for the unified CLI.
+ *
+ * Reads a schema file, converts to ModelMeta[], and generates
+ * models, routes, tests, and OpenAPI spec files.
+ *
+ * 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
+ *
+ * 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
+ */
+async function generate(args, flags, ctx) {
+  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;
+  }
+
+  const meta = schemaToModelMeta(schema);
+  const relationships = schema.relationships || [];
+  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["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 genLlmDocs = !hasArtifactFlag || args["llm-docs"] === true;
+
+  const modelsRelPath = "../models";
+  const baseDir = process.cwd();
+
+  // Collect all planned files: { relPath, content }
+  const planned = [];
+
+  // --- Model files ---
+  if (genModels) {
+    for (const m of meta) {
+      planned.push({
+        relPath: `models/${m.table}.js`,
+        content: generateModelFile(m),
+      });
+    }
+  }
+
+  // --- Route files ---
+  if (genRoutes) {
+    // One route per table
+    for (const m of meta) {
+      planned.push({
+        relPath: `routes/${m.table}.js`,
+        content: generateRouteFile(m.table, modelsRelPath),
+      });
+    }
+
+    // Child route files (one per relationship)
+    for (const rel of relationships) {
+      planned.push({
+        relPath: `routes/${rel.child}_child_of_${rel.parent}.js`,
+        content: generateChildRouteFile(
+          rel.child,
+          rel.parent,
+          rel.foreignKey,
+          modelsRelPath,
+        ),
+      });
+    }
+
+    // Routes index file
+    planned.push({
+      relPath: "routes/index.js",
+      content: generateRoutesIndexFile(tableNames, relationships),
+    });
+  }
+
+  // --- OpenAPI spec ---
+  if (genOpenapi) {
+    planned.push({
+      relPath: "openapi.json",
+      content: JSON.stringify(generateOpenAPISpec(meta), null, 2) + "\n",
+    });
+  }
+
+  // --- Test files ---
+  if (genTests) {
+    for (const m of meta) {
+      planned.push({
+        relPath: `test/${m.table}.test.js`,
+        content: generateTestFile(m.table, m.primary_key),
+      });
+    }
+
+    // Child test files (one per relationship)
+    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`,
+        content: generateChildTestFile(
+          rel.child,
+          rel.parent,
+          rel.foreignKey,
+          pk,
+        ),
+      });
+    }
+  }
+
+  // --- LLM docs ---
+  if (genLlmDocs) {
+    planned.push({
+      relPath: "llms.txt",
+      content: generateLlmsTxt(),
+    });
+    planned.push({
+      relPath: "docs/llm.md",
+      content: generateLlmMd(),
+    });
+  }
+
+  // --- Process planned files ---
+  const results = [];
+
+  for (const { relPath, content } of planned) {
+    const fullPath = path.join(baseDir, relPath);
+
+    if (flags.dryRun) {
+      results.push({ path: relPath, status: "planned" });
+      continue;
+    }
+
+    // Check if file exists and content matches (skip-unchanged)
+    if (fs.existsSync(fullPath)) {
+      const existing = fs.readFileSync(fullPath, "utf8");
+      if (existing === content) {
+        results.push({ path: relPath, status: "unchanged" });
+        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:");
+      for (const r of results) {
+        ctx.log(`  ${r.path}`);
+      }
+      ctx.log(`\n${results.length} file(s) planned.`);
+    }
+  } else if (flags.json) {
+    ctx.result({ files: results });
+  } else {
+    const created = results.filter((r) => r.status === "created").length;
+    const overwritten = results.filter(
+      (r) => r.status === "overwritten",
+    ).length;
+    const unchanged = results.filter((r) => r.status === "unchanged").length;
+    ctx.log(
+      `\nDone. ${created} created, ${overwritten} overwritten, ${unchanged} unchanged.`,
+    );
+  }
+}
+
+module.exports = generate;

package/src/cli/commands/help.js

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

package/src/cli/commands/init.js

@@ -0,0 +1,181 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseSchema } = require("../../schema/schema-parser");
+const {
+  generateFiles,
+  updatePackageJson,
+  runInstall,
+  printSummary,
+  ensurePackageJson,
+} = require("../init");
+const { promptUser } = require("../init/prompt");
+
+/**
+ * Default answers used when --yes is provided and no schema is available.
+ */
+const DEFAULT_ANSWERS = {
+  framework: "express",
+  database: "postgres",
+  session: "memory",
+  rateLimiting: true,
+  helmet: true,
+  logger: true,
+  loki: false,
+};
+
+/**
+ * Init command handler for the unified CLI.
+ *
+ * Scaffolds a new project from a schema file or interactively.
+ *
+ * @param {object} args - Parsed positional/key-value args (e.g. { from, framework, database })
+ * @param {object} flags - Universal flags: { yes, json, dryRun, noInstall, help }
+ * @param {import('../flags').OutputContext} ctx - Output context for --json support
+ */
+async function init(args, flags, ctx) {
+  let answers;
+
+  if (args.from) {
+    // --from points to a schema file: read adapter/framework from it
+    const schemaPath = path.resolve(args.from);
+    if (!fs.existsSync(schemaPath)) {
+      throw new Error(`Schema file not found: ${args.from}`);
+    }
+    const raw = fs.readFileSync(schemaPath, "utf8");
+    const schema = parseSchema(raw);
+
+    answers = {
+      framework: schema.framework,
+      database: schema.adapter,
+      session: (schema.options && schema.options.session) || "memory",
+      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
+    answers = Object.assign({}, DEFAULT_ANSWERS);
+    if (args.framework) answers.framework = args.framework;
+    if (args.database) answers.database = args.database;
+  } else {
+    // Interactive: build prefilled from CLI args, prompt for the rest
+    const prefilled = {};
+    if (args.framework) prefilled.framework = args.framework;
+    if (args.database) prefilled.database = args.database;
+    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, outputDir);
+    if (flags.json) {
+      ctx.result({
+        files: planned,
+        dependencies: { installed: false },
+        actions: ["dry-run"],
+      });
+    } else {
+      ctx.log("Dry run — the following files would be created:");
+      for (const f of planned) {
+        ctx.log(`  ${f}`);
+      }
+      ctx.log("\nNo files were written.");
+    }
+    return;
+  }
+
+  // Ensure package.json exists
+  ensurePackageJson();
+
+  // Generate project files
+  const generated = generateFiles(answers, outputDir);
+
+  // Update package.json with deps and scripts
+  updatePackageJson(answers, outputDir);
+
+  // npm install (unless --no-install)
+  const installed = !flags.noInstall;
+  if (installed) {
+    runInstall();
+  }
+
+  // Output
+  const allFiles = [
+    ...generated.files,
+    ...generated.migrationFiles.map((m) => {
+      const base = outputDir || ".";
+      return base === "." ? `migrations/${m}` : `${base}/migrations/${m}`;
+    }),
+  ];
+
+  if (flags.json) {
+    ctx.result({
+      files: allFiles,
+      dependencies: { installed },
+      actions: installed ? ["scaffolded", "installed"] : ["scaffolded"],
+    });
+  } else {
+    printSummary(generated);
+    if (!installed) {
+      ctx.log(
+        "\nSkipped npm install (--no-install). Run `npm install` manually.",
+      );
+    }
+  }
+}
+
+/**
+ * Compute the list of files that would be created (for --dry-run).
+ * 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, outputDir) {
+  const { isSql } = require("../init/generators");
+  const srcBase = outputDir || ".";
+  const prefix = srcBase === "." ? "" : srcBase + "/";
+
+  const files = [
+    "app.js",
+    ".env",
+    ".env.example",
+    ".gitignore",
+    "Dockerfile",
+    ".dockerignore",
+  ];
+
+  // docker-compose.yml for databases that need Docker
+  if (answers.database !== "sqlite3") {
+    files.push("docker-compose.yml");
+  }
+
+  files.push(
+    `${prefix}middleware/logger.js`,
+    `${prefix}commons/session.js`,
+    `${prefix}commons/migrate.js`,
+    `${prefix}commons/add_migration.js`,
+    `${prefix}commons/security.js`,
+    `${prefix}commons/db.js`,
+    `${prefix}route/health.js`,
+    `${prefix}route/index.js`,
+    `${prefix}migrations/<timestamp>_create_migrations_table` +
+      (isSql(answers.database) ? ".sql" : ".js"),
+  );
+
+  if (answers.session === "database" && isSql(answers.database)) {
+    files.push(`${prefix}migrations/<timestamp>_create_sessions_table.sql`);
+  }
+
+  return files;
+}
+
+module.exports = init;