db-model-router 1.0.0 → 1.0.3

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/init.js

@@ -0,0 +1,153 @@
+"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: false,
+  helmet: false,
+  logger: 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),
+    };
+  } 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);
+  }
+
+  // --dry-run: report planned files without writing
+  if (flags.dryRun) {
+    const planned = planFiles(answers);
+    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);
+
+  // Update package.json with deps and scripts
+  updatePackageJson(answers);
+
+  // npm install (unless --no-install)
+  const installed = !flags.noInstall;
+  if (installed) {
+    runInstall();
+  }
+
+  // Output
+  const allFiles = [
+    ...generated.files,
+    ...generated.migrationFiles.map((m) => `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
+ * @returns {string[]}
+ */
+function planFiles(answers) {
+  const { isSql } = require("../init/generators");
+  const files = [
+    "app.js",
+    ".env",
+    ".env.example",
+    "middleware/logger.js",
+    "migrate.js",
+    "add_migration.js",
+    ".gitignore",
+    "migrations/<timestamp>_create_migrations_table" +
+      (isSql(answers.database) ? ".sql" : ".js"),
+  ];
+
+  if (answers.session === "database" && isSql(answers.database)) {
+    files.push("migrations/<timestamp>_create_sessions_table.sql");
+  }
+
+  return files;
+}
+
+module.exports = init;

package/src/cli/commands/inspect.js

@@ -0,0 +1,205 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { printSchema } = require("../../schema/schema-printer");
+const {
+  introspectMySQL,
+  introspectPostgres,
+  introspectSQLite3,
+  introspectMSSQL,
+  introspectOracle,
+  introspectCockroachDB,
+} = require("../generate-model");
+
+/**
+ * Map of adapter names to their introspection functions.
+ * Each value is an async function(db) => ModelMeta[].
+ */
+const INTROSPECT_MAP = {
+  mysql: introspectMySQL,
+  postgres: introspectPostgres,
+  sqlite3: introspectSQLite3,
+  mssql: introspectMSSQL,
+  oracle: introspectOracle,
+  cockroachdb: introspectCockroachDB,
+};
+
+/**
+ * Convert a ModelMeta array (from introspection) into a ParsedSchema object.
+ * This is the reverse of schemaToModelMeta.
+ *
+ * @param {string} adapter - The database adapter name
+ * @param {string} framework - The framework name (default: "express")
+ * @param {Array<{table, structure, primary_key, unique, option}>} models
+ * @returns {object} ParsedSchema
+ */
+function modelMetaToSchema(adapter, framework, models) {
+  const tables = {};
+
+  for (const m of models) {
+    const columns = {};
+
+    // Re-add columns from structure
+    for (const [col, rule] of Object.entries(m.structure)) {
+      columns[col] = rule;
+    }
+
+    const pk = m.primary_key || "id";
+    const unique = m.unique && m.unique.length > 0 ? [...m.unique] : [pk];
+
+    const opt = m.option || {};
+    const softDelete = opt.safeDelete || null;
+    const timestamps = {
+      created_at: opt.created_at || null,
+      modified_at: opt.modified_at || null,
+    };
+
+    tables[m.table] = {
+      name: m.table,
+      columns,
+      pk,
+      unique,
+      softDelete,
+      timestamps,
+    };
+  }
+
+  return {
+    adapter,
+    framework: framework || "express",
+    tables,
+    relationships: [],
+    options: {},
+  };
+}
+
+/**
+ * Inspect command handler for the unified CLI.
+ *
+ * Connects to a live database, introspects its structure, converts to
+ * ParsedSchema, prints via schema-printer, and writes to file.
+ *
+ * Supported flags:
+ *   --type     Database adapter type (required)
+ *   --env      Path to .env file for connection params
+ *   --out      Output file path (default: dbmr.schema.json)
+ *   --tables   Comma-separated list of tables to include
+ *   --json     Output schema to stdout as JSON (no file write)
+ *   --dry-run  Output schema to stdout without writing file
+ *
+ * @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 inspect(args, flags, ctx) {
+  const adapterType = args.type;
+  if (!adapterType || !INTROSPECT_MAP[adapterType]) {
+    const supported = Object.keys(INTROSPECT_MAP).join(", ");
+    const msg = adapterType
+      ? `Unsupported --type "${adapterType}". Supported: ${supported}`
+      : `Missing required --type flag. Supported: ${supported}`;
+    if (flags.json) {
+      ctx.result({ error: true, code: "INVALID_TYPE", message: msg });
+    } else {
+      ctx.log(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // Load .env file if --env provided
+  if (args.env) {
+    require("dotenv").config({ path: path.resolve(args.env) });
+  }
+
+  // Connect to database
+  let db;
+  try {
+    const restRouter = require("../../index.js");
+    restRouter.init(adapterType);
+    db = restRouter.db;
+
+    const config = {
+      host: process.env.DB_HOST || "localhost",
+      port: process.env.DB_PORT,
+      database: process.env.DB_NAME,
+      user: process.env.DB_USER,
+      password: process.env.DB_PASS,
+      filename: process.env.DB_NAME,
+      server: process.env.DB_HOST || "localhost",
+      options: { encrypt: false, trustServerCertificate: true },
+    };
+
+    db.connect(config);
+  } catch (err) {
+    const msg = `Database connection failed: ${err.message}`;
+    if (flags.json) {
+      ctx.result({ error: true, code: "CONNECTION_FAILED", message: msg });
+    } else {
+      ctx.log(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // Introspect
+  let models;
+  try {
+    const introspectFn = INTROSPECT_MAP[adapterType];
+    models = await introspectFn(db);
+  } catch (err) {
+    const msg = `Introspection failed: ${err.message}`;
+    if (flags.json) {
+      ctx.result({ error: true, code: "INTROSPECTION_FAILED", message: msg });
+    } else {
+      ctx.log(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    // Disconnect
+    if (db.disconnect) await db.disconnect();
+    else if (db.close) db.close();
+    return;
+  }
+
+  // Disconnect
+  try {
+    if (db.disconnect) await db.disconnect();
+    else if (db.close) db.close();
+  } catch (_) {
+    // ignore disconnect errors
+  }
+
+  // Filter by --tables if provided
+  if (args.tables) {
+    const allowed = new Set(args.tables.split(",").map((s) => s.trim()));
+    models = models.filter((m) => allowed.has(m.table));
+  }
+
+  // Convert ModelMeta[] → ParsedSchema
+  const schema = modelMetaToSchema(adapterType, "express", models);
+
+  // Print via schema-printer
+  const output = printSchema(schema);
+
+  // Determine output path
+  const outPath = args.out || "dbmr.schema.json";
+
+  if (flags.json) {
+    // --json: output schema to stdout, no file write
+    ctx.result({ schema: JSON.parse(output), writtenTo: null });
+  } else if (flags.dryRun) {
+    // --dry-run: output schema to stdout, no file write
+    ctx.log(output);
+    ctx.log(`Would write to: ${outPath}`);
+  } else {
+    // Write to file
+    const resolvedPath = path.resolve(outPath);
+    fs.writeFileSync(resolvedPath, output, "utf8");
+    ctx.log(`Schema written to ${outPath}`);
+    ctx.log(output);
+  }
+}
+
+module.exports = inspect;
+module.exports.modelMetaToSchema = modelMetaToSchema;