@web-ts-toolkit/express-runtime 0.25.0 → 0.27.0

package/cli.js

@@ -6,6 +6,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -23,22 +30,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/cli-utils.ts
-var import_node_url = require("url");
-var import_node_path = require("path");
-var import_node_fs = require("fs");
-var import_node_module = require("module");
-var import_node_child_process = require("child_process");
-
 // src/index.ts
-var import_node_http = __toESM(require("http"));
-var import_express = __toESM(require("express"));
-var import_serverless_http = __toESM(require("serverless-http"));
-var defaultLogger = {
-  log: (...args) => console.log(...args),
-  error: (...args) => console.error(...args),
-  debug: (...args) => console.debug(...args)
-};
 function applySettings(app, options) {
   if (options.disablePoweredBy !== false) {
     app.disable("x-powered-by");
@@ -83,8 +75,6 @@ function createExpressApp(options = {}) {
   }
   return app;
 }
-var DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
-var DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
 function normalizePort(val) {
   if (val === void 0 || val === "") {
     const envPort = process.env.PORT;
@@ -194,10 +184,24 @@ function startLocalServer(app, options = {}) {
     shutdown
   };
 }
+var import_node_http, import_express, import_serverless_http, defaultLogger, DEFAULT_SIGNALS, DEFAULT_SHUTDOWN_TIMEOUT;
+var init_src = __esm({
+  "src/index.ts"() {
+    "use strict";
+    import_node_http = __toESM(require("http"));
+    import_express = __toESM(require("express"));
+    import_serverless_http = __toESM(require("serverless-http"));
+    defaultLogger = {
+      log: (...args) => console.log(...args),
+      error: (...args) => console.error(...args),
+      debug: (...args) => console.debug(...args)
+    };
+    DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+    DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
+  }
+});
 
 // src/cli-utils.ts
-var import_meta = {};
-var CLI_VERSION = "0.0.0-PLACEHOLDER";
 function readValue(argv, index, name) {
   const value = argv[index + 1];
   if (value === void 0 || value.startsWith("--")) {
@@ -208,7 +212,7 @@ function readValue(argv, index, name) {
 function printHelp() {
   console.log(`wtt-express-runtime
 
-Run an Express app locally, bundle it as a serverless handler, or run the bundle.
+Run an Express app locally, bundle it for local or serverless runtimes, or run the bundle.
 
 Usage:
   wtt-express-runtime <command> <app-module> [options]
@@ -216,8 +220,10 @@ Usage:
 
 Commands:
   dev                           Run the Express app as a local dev server
-  build                         Bundle the Express app as a serverless handler
-  start                         Run a bundled serverless handler locally
+  build                         Bundle the Express app as a local app module
+  start                         Run a bundled local app module
+  build-serverless              Bundle the Express app as a serverless handler
+  start-serverless              Run a bundled serverless handler locally
 
 Dev options:
   --port <number>               Port or named pipe (default: process.env.PORT or 8080)
@@ -233,13 +239,30 @@ Dev options:
 Build options:
   --init <path>                 Init hook module (default export, async function)
   --out-dir <path>              Output directory (default: dist)
-  --out-name <name>             Output filename without extension (default: handler)
+  --out-name <name>             Output filename without extension (default: app)
   --format <cjs|esm>            Output format (default: cjs)
   --target <target>             Compilation target (default: node22)
   --external <pkg>              Mark package as external (repeatable; express always external)
   --no-clean                    Don't clean the output directory before building
 
 Start options:
+  --port <number>               Port or named pipe (default: process.env.PORT or 8080)
+  --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
+  --no-signals                  Disable SIGINT/SIGTERM handler registration
+  --shutdown-timeout <ms>       Max ms to wait for in-flight requests (default: 5000)
+  --require <module>            Module(s) to preload before app load (repeatable)
+  --env <path>                  Env file(s) to load (repeatable; existing env vars are not overridden)
+
+Build-serverless options:
+  --init <path>                 Init hook module (default export, async function)
+  --out-dir <path>              Output directory (default: dist)
+  --out-name <name>             Output filename without extension (default: handler)
+  --format <cjs|esm>            Output format (default: cjs)
+  --target <target>             Compilation target (default: node22)
+  --external <pkg>              Mark package as external (repeatable; express always external)
+  --no-clean                    Don't clean the output directory before building
+
+Start-serverless options:
   --port <number>               Port or named pipe (default: process.env.PORT or 8080)
   --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
   --no-signals                  Disable SIGINT/SIGTERM handler registration
@@ -255,10 +278,12 @@ Examples:
   wtt-express-runtime dev ./dist/app.js
   wtt-express-runtime dev ./dist/app.js --port 3000 --host localhost
   wtt-express-runtime dev ./src/app.ts --env .env --require tsconfig-paths/register --watch ./src,./shared
-  wtt-express-runtime build ./src/app.ts --out-dir netlify/functions
-  wtt-express-runtime build ./src/app.ts --init ./src/init.ts --format esm
-  wtt-express-runtime start ./netlify/functions/handler.js --port 9000 --env .env
-  wtt-express-runtime build ./src/app.ts && wtt-express-runtime start ./dist/handler.js
+  wtt-express-runtime build ./src/app.ts --out-dir dist
+  wtt-express-runtime start ./dist/app.js --port 3000 --env .env
+  wtt-express-runtime build-serverless ./src/app.ts --out-dir netlify/functions
+  wtt-express-runtime build-serverless ./src/app.ts --init ./src/init.ts --format esm
+  wtt-express-runtime start-serverless ./netlify/functions/handler.js --port 9000 --env .env
+  wtt-express-runtime build-serverless ./src/app.ts && wtt-express-runtime start-serverless ./dist/handler.js
 
 Notes:
   - In dev mode, the CLI evaluates arbitrary code from <app-module> in the current process.
@@ -269,9 +294,11 @@ Notes:
     For advanced dotenv features (multiline, expansion), --require dotenv/config instead.
   - --watch forks a child process running the same CLI without --watch. On file change,
     the child is killed (SIGTERM) and respawned after the debounce delay.
-  - In build mode, express is always external. Add more externals with --external.
-  - In start mode, the bundled handler file must be a JS/CJS module whose "handler"
-    export (or default export) is a function: (event, context) => Promise<result>.
+  - In build/build-serverless mode, express is always external. Add more externals with --external.
+  - In start mode, the bundled app file must default-export an Express app (or export it as "app").
+    If the bundle exports "init", it runs before the server starts listening.
+  - In start-serverless mode, the bundled handler file must be a JS/CJS module whose
+    "handler" export (or default export) is a function: (event, context) => Promise<result>.
   - Init logic for dev mode (DB connections, etc.): add at the top level of your app module.
 `);
 }
@@ -282,10 +309,8 @@ function isHelp(arg) {
   return arg === "-h" || arg === "--help";
 }
 function isSubcommand(arg) {
-  return arg === "dev" || arg === "build" || arg === "start";
+  return arg === "dev" || arg === "build" || arg === "start" || arg === "build-serverless" || arg === "start-serverless";
 }
-var DEFAULT_WATCH_EXTENSIONS = ["ts", "js", "mjs", "cjs", "json"];
-var DEFAULT_WATCH_DELAY = 500;
 function parseRepeatable(argv, index, arg, list) {
   const value = readValue(argv, index, arg);
   for (const part of value.split(",")) {
@@ -423,13 +448,25 @@ function parseDevArgs(argv) {
     watchDelay: watchDelay ?? DEFAULT_WATCH_DELAY
   };
 }
-function parseStartArgs(argv) {
+function parseStartLikeArgs(argv, subcommandName) {
   for (const arg of argv) {
     if (arg === "--watch" || arg.startsWith("--watch=") || arg === "--ext" || arg.startsWith("--ext=") || arg === "--delay" || arg.startsWith("--delay=")) {
-      throw new Error(`--watch/--ext/--delay are not supported with the start subcommand`);
+      throw new Error(`--watch/--ext/--delay are not supported with the ${subcommandName} subcommand`);
     }
   }
-  const result = parseDevArgs(argv);
+  return parseDevArgs(argv);
+}
+function parseStartArgs(argv) {
+  const result = parseStartLikeArgs(argv, "start");
+  return {
+    appPath: result.appPath,
+    options: result.options,
+    require: result.require,
+    env: result.env
+  };
+}
+function parseStartServerlessArgs(argv) {
+  const result = parseStartLikeArgs(argv, "start-serverless");
   return {
     handlerPath: result.appPath,
     options: result.options,
@@ -437,13 +474,13 @@ function parseStartArgs(argv) {
     env: result.env
   };
 }
-function parseBuildArgs(argv) {
+function parseBuildArgs(argv, outNameDefault) {
   let appPath;
   const external = [];
   const result = {
     initPath: void 0,
     outDir: "dist",
-    outName: "handler",
+    outName: outNameDefault,
     format: "cjs",
     target: "node22",
     external,
@@ -538,6 +575,12 @@ function parseBuildArgs(argv) {
   }
   return { appPath, ...result };
 }
+function parseLocalBuildArgs(argv) {
+  return parseBuildArgs(argv, "app");
+}
+function parseBuildServerlessArgs(argv) {
+  return parseBuildArgs(argv, "handler");
+}
 function parseArgs(argv) {
   if (argv.length === 0) {
     printHelp();
@@ -557,10 +600,16 @@ function parseArgs(argv) {
     if (first === "dev") {
       return { subcommand: "dev", dev: parseDevArgs(rest) };
     }
+    if (first === "build") {
+      return { subcommand: "build", build: parseLocalBuildArgs(rest) };
+    }
     if (first === "start") {
       return { subcommand: "start", start: parseStartArgs(rest) };
     }
-    return { subcommand: "build", build: parseBuildArgs(rest) };
+    if (first === "build-serverless") {
+      return { subcommand: "build-serverless", buildServerless: parseBuildServerlessArgs(rest) };
+    }
+    return { subcommand: "start-serverless", startServerless: parseStartServerlessArgs(rest) };
   }
   return { subcommand: "dev", dev: parseDevArgs(argv) };
 }
@@ -634,9 +683,6 @@ function loadEnvFiles(paths) {
     }
   }
 }
-var moduleRequire = (0, import_node_module.createRequire)(
-  typeof import_meta !== "undefined" && import_meta.url || (0, import_node_path.resolve)(process.cwd(), "x").replace(/x$/, "")
-);
 async function preloadModules(modules) {
   for (const mod of modules) {
     moduleRequire(mod);
@@ -716,7 +762,6 @@ function runWithWatch(args) {
   process.on("SIGTERM", shutdown);
   spawnChild();
 }
-var TEMP_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
 function generateServerlessEntry(appPath, initPath) {
   const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
   const absInitPath = initPath ? (0, import_node_path.resolve)(process.cwd(), initPath) : void 0;
@@ -734,16 +779,28 @@ function generateServerlessEntry(appPath, initPath) {
   lines.push(`export { handler };`);
   return lines.join("\n") + "\n";
 }
-async function buildServerless(args) {
+function generateRuntimeEntry(appPath, initPath) {
+  const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const absInitPath = initPath ? (0, import_node_path.resolve)(process.cwd(), initPath) : void 0;
+  const lines = [
+    "// Auto-generated by @web-ts-toolkit/express-runtime CLI \u2014 do not edit.",
+    `import app from ${JSON.stringify(absAppPath)};`,
+    "export default app;",
+    "export { app };"
+  ];
+  if (absInitPath) {
+    lines.push(`export { default as init } from ${JSON.stringify(absInitPath)};`);
+  }
+  return lines.join("\n") + "\n";
+}
+async function buildBundleFromEntryContent(args) {
   const tsupModule = await import("tsup");
   const { build } = tsupModule;
-  const entryContent = generateServerlessEntry(args.appPath, args.initPath);
-  const tempEntryPath = (0, import_node_path.resolve)(process.cwd(), TEMP_ENTRY_FILENAME);
-  (0, import_node_fs.writeFileSync)(tempEntryPath, entryContent, "utf8");
+  const tempEntryPath = (0, import_node_path.resolve)(process.cwd(), args.tempEntryFilename);
+  (0, import_node_fs.writeFileSync)(tempEntryPath, args.entryContent, "utf8");
   try {
     await build({
       config: false,
-      // Don't auto-load tsup.config.ts from cwd
       entry: { [args.outName]: tempEntryPath },
       format: [args.format],
       target: args.target,
@@ -758,6 +815,20 @@ async function buildServerless(args) {
     (0, import_node_fs.rmSync)(tempEntryPath, { force: true });
   }
 }
+async function buildRuntime(args) {
+  const { runBuildEntryCommand: runBuildEntryCommand2 } = await Promise.resolve().then(() => (init_cli_api(), cli_api_exports));
+  await runBuildEntryCommand2(args, {
+    generateEntry: generateRuntimeEntry,
+    tempEntryFilename: TEMP_BUILD_ENTRY_FILENAME
+  });
+}
+async function buildServerless(args) {
+  const { runBuildEntryCommand: runBuildEntryCommand2 } = await Promise.resolve().then(() => (init_cli_api(), cli_api_exports));
+  await runBuildEntryCommand2(args, {
+    generateEntry: generateServerlessEntry,
+    tempEntryFilename: TEMP_SERVERLESS_ENTRY_FILENAME
+  });
+}
 function collectBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -816,6 +887,25 @@ function createServerlessAdapterApp(handler) {
     }
   });
 }
+async function loadBuiltApp(appPath) {
+  const fullPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
+  const mod = await import(moduleUrl);
+  const exported = extractExport(mod);
+  if (!exported) {
+    throw new Error(
+      `Module "${appPath}" must default-export an Express app or export it as "app". Exports: ${Object.keys(mod).join(", ")}`
+    );
+  }
+  const init = mod.init;
+  if (init !== void 0 && typeof init !== "function") {
+    throw new Error(`Module "${appPath}" must export "init" as a function when present.`);
+  }
+  return {
+    app: await resolveExport(exported, appPath),
+    init
+  };
+}
 async function loadHandler(handlerPath) {
   const fullPath = (0, import_node_path.resolve)(process.cwd(), handlerPath);
   const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
@@ -828,37 +918,148 @@ async function loadHandler(handlerPath) {
   }
   return exported;
 }
+var import_node_url, import_node_path, import_node_fs, import_node_module, import_node_child_process, import_meta, CLI_VERSION, DEFAULT_WATCH_EXTENSIONS, DEFAULT_WATCH_DELAY, moduleRequire, TEMP_BUILD_ENTRY_FILENAME, TEMP_SERVERLESS_ENTRY_FILENAME;
+var init_cli_utils = __esm({
+  "src/cli-utils.ts"() {
+    "use strict";
+    import_node_url = require("url");
+    import_node_path = require("path");
+    import_node_fs = require("fs");
+    import_node_module = require("module");
+    import_node_child_process = require("child_process");
+    init_src();
+    import_meta = {};
+    CLI_VERSION = "0.0.0-PLACEHOLDER";
+    DEFAULT_WATCH_EXTENSIONS = ["ts", "js", "mjs", "cjs", "json"];
+    DEFAULT_WATCH_DELAY = 500;
+    moduleRequire = (0, import_node_module.createRequire)(
+      typeof import_meta !== "undefined" && import_meta.url || (0, import_node_path.resolve)(process.cwd(), "x").replace(/x$/, "")
+    );
+    TEMP_BUILD_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+    TEMP_SERVERLESS_ENTRY_FILENAME = ".express-runtime-build-serverless-entry.ts";
+  }
+});
 
-// src/cli.ts
-async function main() {
-  const parsedArgs = parseArgs(process.argv.slice(2));
-  if (!parsedArgs) {
+// src/cli-api.ts
+var cli_api_exports = {};
+__export(cli_api_exports, {
+  CLI_VERSION: () => CLI_VERSION,
+  applyServerlessResult: () => applyServerlessResult,
+  buildBundleFromEntryContent: () => buildBundleFromEntryContent,
+  buildChildArgs: () => buildChildArgs,
+  buildRuntime: () => buildRuntime,
+  buildServerless: () => buildServerless,
+  createServerlessAdapterApp: () => createServerlessAdapterApp,
+  extractExport: () => extractExport,
+  generateRuntimeEntry: () => generateRuntimeEntry,
+  generateServerlessEntry: () => generateServerlessEntry,
+  isExpressApp: () => isExpressApp,
+  loadApp: () => loadApp,
+  loadBuiltApp: () => loadBuiltApp,
+  loadEnvFiles: () => loadEnvFiles,
+  loadHandler: () => loadHandler,
+  parseArgs: () => parseArgs,
+  parseEnvFile: () => parseEnvFile,
+  preloadModules: () => preloadModules,
+  printHelp: () => printHelp,
+  readValue: () => readValue,
+  resolveExport: () => resolveExport,
+  runBuildEntryCommand: () => runBuildEntryCommand,
+  runCliCommand: () => runCliCommand,
+  runDevCommand: () => runDevCommand,
+  runExpressDevCommand: () => runExpressDevCommand,
+  runWithWatch: () => runWithWatch,
+  toServerlessEvent: () => toServerlessEvent
+});
+async function runDevCommand(args, runner) {
+  if (args.watch.length > 0) {
+    (runner.watch ?? runWithWatch)(args);
     return;
   }
+  if (args.env.length > 0) {
+    loadEnvFiles(args.env);
+  }
+  await preloadModules(args.require);
+  const loaded = await runner.load(args.appPath);
+  runner.start(loaded, { ...args.options, exitAfterShutdown: true });
+}
+async function runExpressDevCommand(args) {
+  await runDevCommand(args, {
+    load: loadApp,
+    start: (app, options) => {
+      startLocalServer(app, options);
+    }
+  });
+}
+async function runBuildEntryCommand(args, options) {
+  if (options.allowInit === false && args.initPath) {
+    throw new Error(options.initErrorMessage ?? "This build command manages init automatically. Remove --init.");
+  }
+  await buildBundleFromEntryContent({
+    entryContent: options.generateEntry(args.appPath, args.initPath),
+    tempEntryFilename: options.tempEntryFilename,
+    outDir: args.outDir,
+    outName: args.outName,
+    format: args.format,
+    target: args.target,
+    external: args.external,
+    clean: args.clean
+  });
+}
+async function runCliCommand(parsedArgs) {
   if (parsedArgs.subcommand === "dev") {
-    const { dev } = parsedArgs;
-    if (dev.watch.length > 0) {
-      runWithWatch(dev);
-      return;
-    }
-    if (dev.env.length > 0) {
-      loadEnvFiles(dev.env);
-    }
-    await preloadModules(dev.require);
-    const app = await loadApp(dev.appPath);
-    startLocalServer(app, { ...dev.options, exitAfterShutdown: true });
-  } else if (parsedArgs.subcommand === "start") {
+    await runExpressDevCommand(parsedArgs.dev);
+    return;
+  }
+  if (parsedArgs.subcommand === "start") {
     const { start } = parsedArgs;
     if (start.env.length > 0) {
       loadEnvFiles(start.env);
     }
     await preloadModules(start.require);
-    const handler = await loadHandler(start.handlerPath);
+    const { app, init } = await loadBuiltApp(start.appPath);
+    startLocalServer(app, {
+      ...start.options,
+      init: init ? async () => {
+        await init();
+      } : void 0,
+      exitAfterShutdown: true
+    });
+    return;
+  }
+  if (parsedArgs.subcommand === "build") {
+    await buildRuntime(parsedArgs.build);
+    return;
+  }
+  if (parsedArgs.subcommand === "start-serverless") {
+    const { startServerless } = parsedArgs;
+    if (startServerless.env.length > 0) {
+      loadEnvFiles(startServerless.env);
+    }
+    await preloadModules(startServerless.require);
+    const handler = await loadHandler(startServerless.handlerPath);
     const app = createServerlessAdapterApp(handler);
-    startLocalServer(app, { ...start.options, exitAfterShutdown: true });
-  } else {
-    await buildServerless(parsedArgs.build);
+    startLocalServer(app, { ...startServerless.options, exitAfterShutdown: true });
+    return;
+  }
+  await buildServerless(parsedArgs.buildServerless);
+}
+var init_cli_api = __esm({
+  "src/cli-api.ts"() {
+    "use strict";
+    init_src();
+    init_cli_utils();
+  }
+});
+
+// src/cli.ts
+init_cli_api();
+async function main() {
+  const parsedArgs = parseArgs(process.argv.slice(2));
+  if (!parsedArgs) {
+    return;
   }
+  await runCliCommand(parsedArgs);
 }
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);