rtgl 1.4.0 → 2.0.1

package/cli.js

@@ -1,11 +1,5 @@
 #!/usr/bin/env node
 
-import { build, check, scaffold, watch, examples } from "@rettangoli/fe/cli";
-import { check as checkContracts } from "@rettangoli/check/cli";
-import { build as buildBe, check as checkBe, start as startBe, watch as watchBe } from "@rettangoli/be/cli";
-import { generate, screenshot, report, accept } from "@rettangoli/vt/cli";
-import { buildSite, watchSite, initSite } from "@rettangoli/sites/cli";
-import { buildSvg } from "@rettangoli/ui/cli";
 import { Command, InvalidArgumentError } from "commander";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
@@ -15,6 +9,91 @@ const packageJson = JSON.parse(
   readFileSync(new URL("./package.json", import.meta.url)),
 );
 
+const requestedCommand = process.argv[2];
+
+let build;
+let check;
+let scaffold;
+let watch;
+let examples;
+let checkContracts;
+let generate;
+let screenshot;
+let report;
+let accept;
+let buildSite;
+let watchSite;
+let initSite;
+let buildSvg;
+let appBe;
+let buildBe;
+let checkBe;
+let compatBe;
+let dbBe;
+let initBe;
+let manifestBe;
+let resumeBe;
+let scaffoldBe;
+let startBe;
+let testBe;
+let verifyBe;
+let watchBe;
+let loadBeRuntimeConfig;
+
+if (requestedCommand === "fe") {
+  ({ build, check, scaffold, watch, examples } = await import(
+    "@rettangoli/fe/cli",
+  ));
+} else if (requestedCommand === "check") {
+  ({ check: checkContracts } = await import("@rettangoli/check/cli"));
+} else if (requestedCommand === "vt") {
+  ({ generate, screenshot, report, accept } = await import("@rettangoli/vt/cli"));
+} else if (requestedCommand === "sites") {
+  ({ buildSite, watchSite, initSite } = await import("@rettangoli/sites/cli"));
+} else if (requestedCommand === "ui") {
+  ({ buildSvg } = await import("@rettangoli/ui/cli"));
+} else if (requestedCommand === "be") {
+  const localBeCliUrl = new URL("../rettangoli-be/src/cli/index.js", import.meta.url);
+  const beCli = existsSync(localBeCliUrl)
+    ? await import(localBeCliUrl)
+    : await import("@rettangoli/be/cli");
+
+  ({
+    app: appBe,
+    build: buildBe,
+    check: checkBe,
+    compat: compatBe,
+    db: dbBe,
+    init: initBe,
+    manifest: manifestBe,
+    resume: resumeBe,
+    scaffold: scaffoldBe,
+    start: startBe,
+    test: testBe,
+    verify: verifyBe,
+    watch: watchBe,
+  } = beCli);
+
+  const localBeRuntimeConfigUrl = new URL(
+    "../rettangoli-be/src/runtime/loadBeProjectConfig.js",
+    import.meta.url,
+  );
+  const beRuntimeConfig = existsSync(localBeRuntimeConfigUrl)
+    ? await import(localBeRuntimeConfigUrl)
+    : await import("@rettangoli/be/runtime/loadBeProjectConfig");
+  ({ loadBeProjectConfig: loadBeRuntimeConfig } = beRuntimeConfig);
+}
+
+function requireBeCommand(handler, name) {
+  if (typeof handler !== "function") {
+    throw new Error(
+      `@rettangoli/be/cli does not export '${name}'. Reinstall @rettangoli/be at the version required by rettangoli-cli.`,
+    );
+  }
+
+  return handler;
+}
+
 // Function to read config file
 function readConfig() {
   const configPath = resolve(process.cwd(), "rettangoli.config.yaml");
@@ -66,16 +145,105 @@ function parseIsolationOption(value) {
 function resolveBeRuntimePaths(config) {
   const be = config?.be || {};
   const dirs = Array.isArray(be.dirs) && be.dirs.length > 0 ? be.dirs : ["./src/modules"];
+  const runtimeConfig = loadBeRuntimeConfig({ cwd: process.cwd() });
 
   return {
     dirs,
     middlewareDir: be.middlewareDir || "./src/middleware",
     setup: be.setup || "./src/setup.js",
     outdir: be.outdir || "./.rtgl-be/generated",
+    migrationsDir: be.migrationsDir || "./migrations",
     domainErrors: be.domainErrors || {},
+    globalMiddleware: runtimeConfig.globalMiddleware,
   };
 }
 
+function wantsJsonOutput(options) {
+  return options?.json === true || options?.format === "json";
+}
+
+function writeBeCliError({ command, options, ruleId = "RTGL-BE-CLI-001", message }) {
+  if (!wantsJsonOutput(options)) {
+    throw new Error(message);
+  }
+
+  console.log(JSON.stringify({
+    schemaVersion: "rettangoli.cliResult/v1",
+    command,
+    artifactSchemaVersion: "rettangoli.cliError/v1",
+    ok: false,
+    diagnostics: [
+      {
+        schemaVersion: "rettangoli.diagnostic/v1",
+        ruleId,
+        code: ruleId,
+        severity: "error",
+        phase: "cli",
+        message,
+      },
+    ],
+  }, null, 2));
+  process.exitCode = 1;
+  return null;
+}
+
+function requireBeConfig(command, options) {
+  let config;
+  try {
+    config = readConfig();
+  } catch (error) {
+    return writeBeCliError({
+      command,
+      options,
+      ruleId: "RTGL-BE-CLI-003",
+      message: error.message,
+    });
+  }
+
+  if (config) {
+    return config;
+  }
+
+  return writeBeCliError({
+    command,
+    options,
+    message: "rettangoli.config.yaml not found",
+  });
+}
+
+function readOptionalBeConfig(command, options) {
+  try {
+    return {
+      ok: true,
+      config: readConfig(),
+    };
+  } catch (error) {
+    writeBeCliError({
+      command,
+      options,
+      ruleId: "RTGL-BE-CLI-003",
+      message: error.message,
+    });
+    return {
+      ok: false,
+      config: null,
+    };
+  }
+}
+
+function resolveBeRuntimePathsOrReport(command, options, config) {
+  try {
+    return resolveBeRuntimePaths(config);
+  } catch (error) {
+    return writeBeCliError({
+      command,
+      options,
+      ruleId: "RTGL-BE-CLI-003",
+      message: error.message,
+    });
+  }
+}
+
 const program = new Command();
 
 program
@@ -150,7 +318,7 @@ Examples:
   $ rettangoli fe build --setup-path src/setup.web.js
 `,
   )
-  .action((options) => {
+  .action(async (options) => {
     const config = readConfig();
 
     if (!config) {
@@ -180,7 +348,7 @@ Examples:
       options.outfile = config.fe.outfile;
     }
 
-    build(options);
+    await build(options);
   });
 
 feCommand
@@ -261,7 +429,7 @@ Examples:
   $ rettangoli fe watch --setup-path src/setup.web.js
 `,
   )
-  .action((options) => {
+  .action(async (options) => {
     const config = readConfig();
 
     if (!config) {
@@ -291,7 +459,7 @@ Examples:
       options.outfile = config.fe.outfile;
     }
 
-    watch(options);
+    await watch(options);
   });
 
 feCommand
@@ -306,33 +474,57 @@ feCommand
 
 const beCommand = program.command("be").description("Backend framework");
 
+beCommand
+  .command("init")
+  .description("Initialize a minimal backend app")
+  .option("--method <method>", "Initial method id", "health.ping")
+  .option("--dir <path>", "Backend method directory to create under")
+  .option("--dry-run", "Print the init plan without writing files")
+  .option("--check", "Alias for --dry-run")
+  .option("--json", "Output JSON")
+  .action((options) => {
+    options.dirs = options.dir || "./src/modules";
+    if (options.json) options.format = "json";
+    requireBeCommand(initBe, "init")(options);
+  });
+
 beCommand
   .command("build")
   .description("Build backend method registry and app entry")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
   .option("-s, --setup-path <path>", "Custom setup file path")
   .option("-m, --middleware-dir <path>", "Custom middleware directory path")
   .option("-o, --outdir <path>", "Generated output directory")
+  .option("--dry-run", "Print the deterministic build plan without writing files")
+  .option("--check", "Check whether generated files are fresh")
+  .option("--json", "Output JSON")
   .action((options) => {
-    const config = readConfig();
-
-    if (!config) {
-      throw new Error("rettangoli.config.yaml not found");
-    }
+    const config = requireBeConfig("be build", options);
+    if (!config) return;
 
-    const bePaths = resolveBeRuntimePaths(config);
+    const bePaths = resolveBeRuntimePathsOrReport("be build", options, config);
+    if (!bePaths) return;
 
-    const missingDirs = bePaths.dirs.filter(
+    const selectedDirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
+    const missingDirs = selectedDirs.filter(
       (dir) => !existsSync(resolve(process.cwd(), dir)),
     );
     if (missingDirs.length > 0) {
-      throw new Error(`Directories do not exist: ${missingDirs.join(", ")}`);
+      writeBeCliError({
+        command: "be build",
+        options,
+        ruleId: "RTGL-BE-CLI-004",
+        message: `Directories do not exist: ${missingDirs.join(", ")}`,
+      });
+      return;
     }
 
-    options.dirs = bePaths.dirs;
+    options.dirs = selectedDirs;
     options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
     options.setup = options.setupPath || bePaths.setup;
     options.outdir = options.outdir || bePaths.outdir;
     options.domainErrors = bePaths.domainErrors;
+    if (options.json) options.format = "json";
 
     buildBe(options);
   });
@@ -341,27 +533,216 @@ beCommand
   .command("check")
   .description("Validate backend RPC contracts")
   .option("--format <format>", "Output format: text or json", "text")
+  .option("--json", "Output JSON")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
+  .option("--method <method>", "Validate one backend method id")
   .option("-m, --middleware-dir <path>", "Custom middleware directory path")
   .action((options) => {
-    const config = readConfig();
+    const config = requireBeConfig("be check", options);
+    if (!config) return;
 
-    if (!config) {
-      throw new Error("rettangoli.config.yaml not found");
-    }
+    const bePaths = resolveBeRuntimePathsOrReport("be check", options, config);
+    if (!bePaths) return;
 
-    const bePaths = resolveBeRuntimePaths(config);
+    options.dirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
+    options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
+    if (options.json) options.format = "json";
 
-    const missingDirs = bePaths.dirs.filter(
-      (dir) => !existsSync(resolve(process.cwd(), dir)),
-    );
-    if (missingDirs.length > 0) {
-      throw new Error(`Directories do not exist: ${missingDirs.join(", ")}`);
+    checkBe(options);
+  });
+
+beCommand
+  .command("manifest")
+  .description("Print deterministic backend API manifest")
+  .option("--json", "Output JSON")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
+  .option("--method <method>", "Print manifest for one backend method id")
+  .option("-m, --middleware-dir <path>", "Custom middleware directory path")
+  .option("--outdir <path>", "Generated output directory used for target facts")
+  .option("--migrations-dir <path>", "SQLite migrations directory")
+  .option("-o, --output <path>", "Write manifest JSON to a file")
+  .action((options) => {
+    const config = requireBeConfig("be manifest", options);
+    if (!config) return;
+
+    const bePaths = resolveBeRuntimePathsOrReport("be manifest", options, config);
+    if (!bePaths) return;
+
+    options.dirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
+    options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
+    options.outdir = options.outdir || bePaths.outdir;
+    options.migrationsDir = options.migrationsDir || bePaths.migrationsDir;
+
+    requireBeCommand(manifestBe, "manifest")(options);
+  });
+
+beCommand
+  .command("compat")
+  .description("Compare two backend manifests for API compatibility")
+  .option("--from <path>", "Previous manifest JSON")
+  .option("--to <path>", "Current manifest JSON")
+  .option("--json", "Output JSON")
+  .action((options) => {
+    if (options.json) options.format = "json";
+    if (!options.from || !options.to) {
+      writeBeCliError({
+        command: "be compat",
+        options,
+        ruleId: "RTGL-BE-CLI-002",
+        message: "be compat requires --from and --to manifest JSON files.",
+      });
+      return;
     }
+    requireBeCommand(compatBe, "compat")(options);
+  });
 
-    options.dirs = bePaths.dirs;
+beCommand
+  .command("test")
+  .description("Run backend executable examples")
+  .option("--format <format>", "Output format: text or json", "text")
+  .option("--json", "Output JSON")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
+  .option("--method <method>", "Run examples for one backend method id")
+  .option("-s, --setup-path <path>", "Custom setup file path")
+  .option("-m, --middleware-dir <path>", "Custom middleware directory path")
+  .option("--config <path>", "Vitest config path", "./vitest.config.js")
+  .option("--test-config <path>", "Alias for --config")
+  .option("--package-manager <name>", "Package manager for running Vitest: npm, pnpm, yarn, bun")
+  .option("--runner <command>", "Executable used to run Vitest")
+  .action((options) => {
+    const config = requireBeConfig("be test", options);
+    if (!config) return;
+
+    const bePaths = resolveBeRuntimePathsOrReport("be test", options, config);
+    if (!bePaths) return;
+
+    options.dirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
     options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
+    options.setup = options.setupPath || bePaths.setup;
+    options.globalMiddlewareBefore = bePaths.globalMiddleware.before;
+    options.globalMiddlewareAfter = bePaths.globalMiddleware.after;
+    options.config = options.testConfig || options.config;
+    options.executable = options.runner;
+    if (options.json) options.format = "json";
 
-    checkBe(options);
+    requireBeCommand(testBe, "test")(options);
+  });
+
+beCommand
+  .command("verify")
+  .description("Run backend check, build, manifest, and examples")
+  .option("--format <format>", "Output format: text or json", "text")
+  .option("--json", "Output JSON")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
+  .option("--method <method>", "Verify one backend method id")
+  .option("-s, --setup-path <path>", "Custom setup file path")
+  .option("-m, --middleware-dir <path>", "Custom middleware directory path")
+  .option("-o, --outdir <path>", "Generated output directory")
+  .option("--migrations-dir <path>", "SQLite migrations directory")
+  .option("--fail-on-warnings", "Return non-zero when warnings are present")
+  .option("--evidence <taskId>", "Write verification evidence under .rtgl-be/evidence")
+  .option("--task-id <taskId>", "Task id for verification evidence")
+  .option("--config <path>", "Alias for --test-config")
+  .option("--test-config <path>", "Vitest config path", "./vitest.config.js")
+  .option("--package-manager <name>", "Package manager for running Vitest: npm, pnpm, yarn, bun")
+  .option("--runner <command>", "Executable used to run Vitest")
+  .action(async (options) => {
+    const config = requireBeConfig("be verify", options);
+    if (!config) return;
+
+    const bePaths = resolveBeRuntimePathsOrReport("be verify", options, config);
+    if (!bePaths) return;
+
+    options.dirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
+    options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
+    options.setup = options.setupPath || bePaths.setup;
+    options.outdir = options.outdir || bePaths.outdir;
+    options.migrationsDir = options.migrationsDir || bePaths.migrationsDir;
+    options.failOnWarnings = !!options.failOnWarnings;
+    options.globalMiddlewareBefore = bePaths.globalMiddleware.before;
+    options.globalMiddlewareAfter = bePaths.globalMiddleware.after;
+    options.testConfig = options.config || options.testConfig;
+    options.executable = options.runner;
+    if (options.json) options.format = "json";
+
+    await requireBeCommand(verifyBe, "verify")(options);
+  });
+
+const beAppCommand = beCommand.command("app").description("Backend app runtime checks");
+
+beAppCommand
+  .command("check")
+  .description("Import setup, handlers, middleware, and instantiate the backend app")
+  .option("--json", "Output JSON")
+  .option("--dir <path>", "Backend method directory to scan (repeatable)", collectValues, [])
+  .option("--method <method>", "Check one backend method id")
+  .option("-s, --setup-path <path>", "Custom setup file path")
+  .option("-m, --middleware-dir <path>", "Custom middleware directory path")
+  .action(async (options) => {
+    const config = requireBeConfig("be app check", options);
+    if (!config) return;
+    const bePaths = resolveBeRuntimePathsOrReport("be app check", options, config);
+    if (!bePaths) return;
+
+    options.dirs = options.dir.length > 0 ? options.dir : bePaths.dirs;
+    options.middlewareDir = options.middlewareDir || bePaths.middlewareDir;
+    options.setup = options.setupPath || bePaths.setup;
+    options.globalMiddlewareBefore = bePaths.globalMiddleware.before;
+    options.globalMiddlewareAfter = bePaths.globalMiddleware.after;
+    if (options.json) options.format = "json";
+
+    await requireBeCommand(appBe, "app")(options);
+  });
+
+beCommand
+  .command("scaffold [methodId]")
+  .description("Scaffold a backend method package")
+  .option("--method <method>", "Backend method id, e.g. user.getProfile")
+  .option("--dir <path>", "Backend method directory to create under")
+  .option("--dry-run", "Print the scaffold plan without writing files")
+  .option("--check", "Alias for --dry-run")
+  .option("--json", "Output JSON")
+  .action((methodId, options) => {
+    const configResult = readOptionalBeConfig("be scaffold", options);
+    if (!configResult.ok) return;
+    const bePaths = resolveBeRuntimePathsOrReport("be scaffold", options, configResult.config);
+    if (!bePaths) return;
+
+    options.methodId = options.method || methodId;
+    options.dirs = options.dir || bePaths.dirs[0] || "./src/modules";
+    if (options.json) options.format = "json";
+    requireBeCommand(scaffoldBe, "scaffold")(options);
+  });
+
+const beDbCommand = beCommand.command("db").description("SQLite backend database checks");
+
+beDbCommand
+  .command("check")
+  .description("Validate and replay SQLite migrations")
+  .option("--json", "Output JSON")
+  .option("--migrations-dir <path>", "SQLite migrations directory")
+  .option("--fail-on-warnings", "Return non-zero when warnings are present")
+  .action((options) => {
+    const configResult = readOptionalBeConfig("be db check", options);
+    if (!configResult.ok) return;
+    const bePaths = resolveBeRuntimePathsOrReport("be db check", options, configResult.config);
+    if (!bePaths) return;
+
+    options.migrationsDir = options.migrationsDir || bePaths.migrationsDir;
+    options.failOnWarnings = !!options.failOnWarnings;
+    if (options.json) options.format = "json";
+
+    requireBeCommand(dbBe, "db")(options);
+  });
+
+beCommand
+  .command("resume <taskId>")
+  .description("Resume a backend verification task anchor")
+  .option("--json", "Output JSON")
+  .action((taskId, options) => {
+    options.taskId = taskId;
+    if (options.json) options.format = "json";
+    requireBeCommand(resumeBe, "resume")(options);
   });
 
 beCommand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rtgl",
-  "version": "1.4.0",
+  "version": "2.0.1",
   "description": "CLI tool for Rettangoli - A frontend framework and development toolkit",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
   },
   "homepage": "https://rettangoli.dev/",
   "engines": {
-    "node": ">=18.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "publishConfig": {
     "access": "public",
@@ -48,8 +48,8 @@
     "commander": "^14.0.0",
     "js-yaml": "^4.1.0",
     "@rettangoli/check": "0.1.2",
-    "@rettangoli/be": "1.0.2",
-    "@rettangoli/fe": "1.2.0",
+    "@rettangoli/be": "2.0.0",
+    "@rettangoli/fe": "1.2.1",
     "@rettangoli/sites": "1.2.0",
     "@rettangoli/vt": "1.0.5",
     "@rettangoli/ui": "1.4.2"