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

package/README.md

@@ -321,6 +321,8 @@ interface Logger {
 
 ## CLI
 
+Programmatic CLI helpers are also available from the public subpath `@web-ts-toolkit/express-runtime/cli` when another package wants to reuse the same parsing, build, watch, env-loading, or start logic without shelling out to the `wtt-express-runtime` binary.
+
 ### `wtt-express-runtime <command> <app-module> [options]`
 
 Omitting `<command>` defaults to `dev` for backward compatibility.

package/chunk-SOW7OLVN.mjs

@@ -0,0 +1,221 @@
+// src/index.ts
+import http from "http";
+import express from "express";
+import serverless from "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");
+  }
+  app.set("etag", options.etag ?? false);
+  app.set("trust proxy", options.trustProxy ?? false);
+}
+function applyMiddlewareList(app, list) {
+  if (list) {
+    for (const mw of list) {
+      app.use(mw);
+    }
+  }
+}
+function applyRouters(app, options) {
+  const mounts = [];
+  if (options.router) mounts.push(options.router);
+  if (options.routers) mounts.push(...options.routers);
+  for (const mount of mounts) {
+    const path = typeof mount.path === "function" ? mount.path() : mount.path;
+    app.use(path, mount.handler);
+  }
+}
+function createExpressApp(options = {}) {
+  const app = express();
+  applySettings(app, options);
+  applyMiddlewareList(app, options.preMiddleware);
+  if (options.json !== false) {
+    app.use(express.json(options.json ?? { limit: "1mb" }));
+  }
+  if (options.urlencoded !== false) {
+    app.use(express.urlencoded(options.urlencoded ?? { extended: false, limit: "1mb" }));
+  }
+  applyMiddlewareList(app, options.middleware);
+  applyRouters(app, options);
+  applyMiddlewareList(app, options.postMiddleware);
+  if (options.finalize) {
+    options.finalize(app);
+  }
+  if (options.errorHandler) {
+    app.use(options.errorHandler);
+  }
+  return app;
+}
+function defaultRequestHook(req, maxBodyBytes = 1024 * 1024, logger = defaultLogger) {
+  if (!req.body || !Buffer.isBuffer(req.body)) {
+    return;
+  }
+  if (req.body.length > maxBodyBytes) {
+    logger.debug?.(" Skipping oversized serverless body for content-type parsing");
+    return;
+  }
+  try {
+    const bodyStr = req.body.toString("utf8");
+    const contentType = (req.headers?.["content-type"] ?? "").toLowerCase();
+    if (contentType.startsWith("application/json")) {
+      req.body = JSON.parse(bodyStr);
+    } else {
+      req.body = bodyStr;
+    }
+  } catch (error) {
+    logger.error("Failed to parse serverless request body:", error);
+  }
+}
+function createServerlessHandler(app, options = {}) {
+  const logger = options.logger ?? defaultLogger;
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const requestHook = options.request ?? ((req) => defaultRequestHook(req, maxBodyBytes, logger));
+  const baseOptions = {
+    ...options.serverlessOptions ?? {},
+    request: requestHook
+  };
+  if (options.response) {
+    baseOptions.response = options.response;
+  }
+  const apiHandler = serverless(app, baseOptions);
+  let initialized = null;
+  const ensureInit = () => {
+    if (!initialized) {
+      logger.debug?.("Serverless cold start: running init");
+      initialized = options.init ? options.init() : Promise.resolve();
+    }
+    return initialized;
+  };
+  const handler = async (event, context) => {
+    await ensureInit();
+    return apiHandler(event, context);
+  };
+  handler.reset = () => {
+    initialized = null;
+  };
+  return handler;
+}
+var DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+var DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
+function normalizePort(val) {
+  if (val === void 0 || val === "") {
+    const envPort = process.env.PORT;
+    if (envPort === void 0 || envPort === "") {
+      return 8080;
+    }
+    val = envPort;
+  }
+  if (typeof val === "string") {
+    const parsed = Number(val);
+    if (Number.isNaN(parsed)) {
+      return val;
+    }
+    val = parsed;
+  }
+  if (!Number.isFinite(val) || val < 0 || val > 65535) {
+    throw new Error(`Invalid port: ${String(val)}`);
+  }
+  return val;
+}
+function defaultOnError(error, port, logger) {
+  if (error.syscall !== "listen") {
+    throw error;
+  }
+  const bind = typeof port === "string" ? `Pipe ${port}` : `Port ${port}`;
+  if (error.code === "EACCES") {
+    logger.error(`${bind} requires elevated privileges`);
+    process.exit(1);
+  } else if (error.code === "EADDRINUSE") {
+    logger.error(`${bind} is already in use`);
+    process.exit(1);
+  } else {
+    throw error;
+  }
+}
+function startLocalServer(app, options = {}) {
+  const logger = options.logger ?? defaultLogger;
+  const port = normalizePort(options.port);
+  const host = options.host ?? process.env.HOST ?? "0.0.0.0";
+  const shutdownTimeout = options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT;
+  const server = http.createServer(app);
+  app.set("port", port);
+  const onError = (error) => {
+    if (options.onError) {
+      options.onError(error);
+    } else {
+      defaultOnError(error, port, logger);
+    }
+  };
+  const onListening = () => {
+    const addr = server.address();
+    const bind = typeof addr === "string" ? `pipe ${addr}` : `port ${addr?.port}`;
+    logger.log(`Server running at http://${host}:${port}/ (${bind})`);
+    options.onListening?.();
+  };
+  server.on("error", onError);
+  server.on("listening", onListening);
+  const shutdown = async () => {
+    logger.log("Shutting down...");
+    try {
+      if (options.onShutdown) {
+        await options.onShutdown();
+      }
+    } catch (err) {
+      logger.error("onShutdown hook failed:", err);
+    }
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        server.closeAllConnections?.();
+        resolve();
+      }, shutdownTimeout);
+      server.close((err) => {
+        clearTimeout(timer);
+        if (err) {
+          logger.error("Server close error:", err);
+        }
+        resolve();
+      });
+    });
+    if (options.exitAfterShutdown) {
+      process.exit(0);
+    }
+  };
+  if (options.signals !== false) {
+    const list = options.signals === void 0 || options.signals === true ? DEFAULT_SIGNALS : options.signals;
+    for (const sig of list) {
+      process.once(sig, () => void shutdown());
+    }
+  }
+  const start = async () => {
+    try {
+      if (options.init) {
+        await options.init();
+      }
+      if (typeof port === "number") {
+        server.listen(port, host);
+      } else {
+        server.listen(port);
+      }
+    } catch (err) {
+      server.emit("error", err);
+    }
+  };
+  void start();
+  return {
+    server,
+    shutdown
+  };
+}
+
+export {
+  createExpressApp,
+  defaultRequestHook,
+  createServerlessHandler,
+  normalizePort,
+  startLocalServer
+};

package/cli-api.d.mts

@@ -0,0 +1,237 @@
+import { Response, Express } from 'express';
+import { LocalServerOptions } from './index.mjs';
+import 'node:http';
+import 'serverless-http';
+
+/**
+ * Version placeholder rewritten at publish time by `@repo-toolkit/publish-package`.
+ */
+declare const CLI_VERSION = "0.0.0-PLACEHOLDER";
+/**
+ * Read the next argv value after a flag, throwing if it is missing or looks
+ * like another flag.
+ */
+declare function readValue(argv: string[], index: number, name: string): string;
+type Subcommand = 'dev' | 'build' | 'start' | 'build-serverless' | 'start-serverless';
+interface DevArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the app (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app (repeatable `--env`). */
+    env: string[];
+    /** Directories to watch for changes (repeatable `--watch`). */
+    watch: string[];
+    /** File extensions to watch (default: ts,js,mjs,cjs,json). */
+    watchExt: string[];
+    /** Debounce delay (ms) before restarting on file change (default: 500). */
+    watchDelay: number;
+}
+interface BuildArgs {
+    appPath: string;
+    initPath?: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface BuildEntryContentArgs {
+    entryContent: string;
+    tempEntryFilename: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface StartArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'onShutdown'>;
+    /** Modules to preload before loading the app bundle (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app bundle (repeatable `--env`). */
+    env: string[];
+}
+interface StartServerlessArgs {
+    handlerPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the handler (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the handler (repeatable `--env`). */
+    env: string[];
+}
+type ParsedArgs = {
+    subcommand: 'dev';
+    dev: DevArgs;
+} | {
+    subcommand: 'build';
+    build: BuildArgs;
+} | {
+    subcommand: 'build-serverless';
+    buildServerless: BuildArgs;
+} | {
+    subcommand: 'start';
+    start: StartArgs;
+} | {
+    subcommand: 'start-serverless';
+    startServerless: StartServerlessArgs;
+} | null;
+declare function printHelp(): void;
+declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Type-guard: an Express app is a function with `listen` and `use` methods.
+ */
+declare function isExpressApp(x: unknown): x is Express;
+/**
+ * Extract the primary export from a loaded module: prefer `default`, fall back
+ * to a named `app`.
+ */
+declare function extractExport(mod: Record<string, unknown>): unknown;
+/**
+ * Resolve a raw export into an Express app, awaiting an async factory if
+ * needed. Throws with a friendly message on incompatible exports.
+ */
+declare function resolveExport(exported: unknown, appPath: string): Promise<Express>;
+/**
+ * Dynamically import a module and resolve its primary export to an Express app.
+ */
+declare function loadApp(appPath: string): Promise<Express>;
+/**
+ * Parse env file content as KEY=VALUE lines. Supports `export` prefix,
+ * single/double-quoted values, and `#` comments. Returns parsed entries.
+ *
+ * Exported for direct unit testing.
+ */
+declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Load env files into `process.env`. Existing environment variables are
+ * **not** overridden (consistent with dotenv's default behavior). Missing
+ * files throw with a friendly message.
+ *
+ * Exported for direct unit testing.
+ */
+declare function loadEnvFiles(paths: string[]): void;
+/**
+ * Preload modules (e.g. `tsconfig-paths/register`, `dotenv/config`) before
+ * loading the app module. Each module is `require()`-ed, running its
+ * side effects (registering hooks, loading configs, etc.).
+ *
+ * Exported for direct unit testing.
+ */
+declare function preloadModules(modules: string[]): Promise<void>;
+/**
+ * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
+ * flags (the child runs without watch mode).
+ *
+ * Exported for direct unit testing.
+ */
+declare function buildChildArgs(args: DevArgs): string[];
+/**
+ * Run the CLI in watch mode. Forks a child process running the same CLI
+ * without --watch, watches the specified paths for file changes, and
+ * restarts the child (SIGTERM → respawn) on changes matching the given
+ * extensions. Uses Node 20+'s `fs.watch` with `{ recursive: true }`.
+ */
+declare function runWithWatch(args: DevArgs): void;
+type RuntimeModuleInit = () => Promise<void> | void;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a serverless handler.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateServerlessEntry(appPath: string, initPath?: string): string;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a local runtime bundle.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateRuntimeEntry(appPath: string, initPath?: string): string;
+declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
+/**
+ * Bundle an Express app as a local runtime module. The output default-exports
+ * the app and may additionally export an `init` hook for the `start` command.
+ */
+declare function buildRuntime(args: BuildArgs): Promise<void>;
+/**
+ * Bundle an Express app as a serverless handler. Writes a temporary entry file
+ * to the user's cwd (for node_modules resolution), lazy-loads the bundled
+ * build tool, then cleans up.
+ *
+ * `express` is always external; additional externals can be passed via
+ * `BuildArgs.external`.
+ */
+declare function buildServerless(args: BuildArgs): Promise<void>;
+/**
+ * A platform-agnostic serverless handler function (the output of
+ * `build-serverless`).
+ */
+type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
+/**
+ * The result shape returned by `serverless-http` (and the `build` output).
+ */
+interface ServerlessResult {
+    statusCode?: number;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: string;
+    isBase64Encoded?: boolean;
+}
+/**
+ * Build a serverless event from HTTP request components.
+ *
+ * Exported for direct unit testing.
+ */
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): Record<string, unknown>;
+/**
+ * Write a serverless handler result to an Express response.
+ *
+ * Exported for direct unit testing.
+ */
+declare function applyServerlessResult(result: unknown, res: Response): void;
+/**
+ * Create an Express app that proxies all requests to a serverless handler.
+ * Each HTTP request is translated into a serverless event, the handler is
+ * invoked, and the result is written back to the response.
+ *
+ * Express body parsers are disabled; the raw request body is read directly
+ * from the stream and passed as a Buffer (so the serverless handler's request
+ * hook — including the #305 workaround — works identically to production).
+ */
+declare function createServerlessAdapterApp(handler: GenericHandler): Express;
+/**
+ * Load a bundled app module from the `build` output.
+ */
+declare function loadBuiltApp(appPath: string): Promise<{
+    app: Express;
+    init?: RuntimeModuleInit;
+}>;
+/**
+ * Load a bundled serverless handler from a JS/CJS module. The module must
+ * export a `handler` function (or use `default` export).
+ */
+declare function loadHandler(handlerPath: string): Promise<GenericHandler>;
+
+type RuntimeCliCommand = Exclude<ParsedArgs, null>;
+interface DevCommandRunner<TLoaded> {
+    load: (appPath: string) => Promise<TLoaded> | TLoaded;
+    start: (loaded: TLoaded, options: DevArgs['options'] & {
+        exitAfterShutdown: true;
+    }) => void;
+    watch?: (args: DevArgs) => void;
+}
+interface BuildEntryCommandOptions {
+    generateEntry: (appPath: string, initPath?: string) => string;
+    tempEntryFilename: string;
+    allowInit?: boolean;
+    initErrorMessage?: string;
+}
+declare function runDevCommand<TLoaded>(args: DevArgs, runner: DevCommandRunner<TLoaded>): Promise<void>;
+declare function runExpressDevCommand(args: DevArgs): Promise<void>;
+declare function runBuildEntryCommand(args: BuildArgs, options: BuildEntryCommandOptions): Promise<void>;
+declare function runCliCommand(parsedArgs: RuntimeCliCommand): Promise<void>;
+
+export { type BuildArgs, type BuildEntryCommandOptions, type BuildEntryContentArgs, CLI_VERSION, type DevArgs, type DevCommandRunner, type GenericHandler, type ParsedArgs, type RuntimeCliCommand, type RuntimeModuleInit, type ServerlessResult, type StartArgs, type StartServerlessArgs, type Subcommand, applyServerlessResult, buildBundleFromEntryContent, buildChildArgs, buildRuntime, buildServerless, createServerlessAdapterApp, extractExport, generateRuntimeEntry, generateServerlessEntry, isExpressApp, loadApp, loadBuiltApp, loadEnvFiles, loadHandler, parseArgs, parseEnvFile, preloadModules, printHelp, readValue, resolveExport, runBuildEntryCommand, runCliCommand, runDevCommand, runExpressDevCommand, runWithWatch, toServerlessEvent };

package/cli-api.d.ts

@@ -0,0 +1,237 @@
+import { Response, Express } from 'express';
+import { LocalServerOptions } from './index.js';
+import 'node:http';
+import 'serverless-http';
+
+/**
+ * Version placeholder rewritten at publish time by `@repo-toolkit/publish-package`.
+ */
+declare const CLI_VERSION = "0.0.0-PLACEHOLDER";
+/**
+ * Read the next argv value after a flag, throwing if it is missing or looks
+ * like another flag.
+ */
+declare function readValue(argv: string[], index: number, name: string): string;
+type Subcommand = 'dev' | 'build' | 'start' | 'build-serverless' | 'start-serverless';
+interface DevArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the app (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app (repeatable `--env`). */
+    env: string[];
+    /** Directories to watch for changes (repeatable `--watch`). */
+    watch: string[];
+    /** File extensions to watch (default: ts,js,mjs,cjs,json). */
+    watchExt: string[];
+    /** Debounce delay (ms) before restarting on file change (default: 500). */
+    watchDelay: number;
+}
+interface BuildArgs {
+    appPath: string;
+    initPath?: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface BuildEntryContentArgs {
+    entryContent: string;
+    tempEntryFilename: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface StartArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'onShutdown'>;
+    /** Modules to preload before loading the app bundle (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app bundle (repeatable `--env`). */
+    env: string[];
+}
+interface StartServerlessArgs {
+    handlerPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the handler (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the handler (repeatable `--env`). */
+    env: string[];
+}
+type ParsedArgs = {
+    subcommand: 'dev';
+    dev: DevArgs;
+} | {
+    subcommand: 'build';
+    build: BuildArgs;
+} | {
+    subcommand: 'build-serverless';
+    buildServerless: BuildArgs;
+} | {
+    subcommand: 'start';
+    start: StartArgs;
+} | {
+    subcommand: 'start-serverless';
+    startServerless: StartServerlessArgs;
+} | null;
+declare function printHelp(): void;
+declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Type-guard: an Express app is a function with `listen` and `use` methods.
+ */
+declare function isExpressApp(x: unknown): x is Express;
+/**
+ * Extract the primary export from a loaded module: prefer `default`, fall back
+ * to a named `app`.
+ */
+declare function extractExport(mod: Record<string, unknown>): unknown;
+/**
+ * Resolve a raw export into an Express app, awaiting an async factory if
+ * needed. Throws with a friendly message on incompatible exports.
+ */
+declare function resolveExport(exported: unknown, appPath: string): Promise<Express>;
+/**
+ * Dynamically import a module and resolve its primary export to an Express app.
+ */
+declare function loadApp(appPath: string): Promise<Express>;
+/**
+ * Parse env file content as KEY=VALUE lines. Supports `export` prefix,
+ * single/double-quoted values, and `#` comments. Returns parsed entries.
+ *
+ * Exported for direct unit testing.
+ */
+declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Load env files into `process.env`. Existing environment variables are
+ * **not** overridden (consistent with dotenv's default behavior). Missing
+ * files throw with a friendly message.
+ *
+ * Exported for direct unit testing.
+ */
+declare function loadEnvFiles(paths: string[]): void;
+/**
+ * Preload modules (e.g. `tsconfig-paths/register`, `dotenv/config`) before
+ * loading the app module. Each module is `require()`-ed, running its
+ * side effects (registering hooks, loading configs, etc.).
+ *
+ * Exported for direct unit testing.
+ */
+declare function preloadModules(modules: string[]): Promise<void>;
+/**
+ * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
+ * flags (the child runs without watch mode).
+ *
+ * Exported for direct unit testing.
+ */
+declare function buildChildArgs(args: DevArgs): string[];
+/**
+ * Run the CLI in watch mode. Forks a child process running the same CLI
+ * without --watch, watches the specified paths for file changes, and
+ * restarts the child (SIGTERM → respawn) on changes matching the given
+ * extensions. Uses Node 20+'s `fs.watch` with `{ recursive: true }`.
+ */
+declare function runWithWatch(args: DevArgs): void;
+type RuntimeModuleInit = () => Promise<void> | void;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a serverless handler.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateServerlessEntry(appPath: string, initPath?: string): string;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a local runtime bundle.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateRuntimeEntry(appPath: string, initPath?: string): string;
+declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
+/**
+ * Bundle an Express app as a local runtime module. The output default-exports
+ * the app and may additionally export an `init` hook for the `start` command.
+ */
+declare function buildRuntime(args: BuildArgs): Promise<void>;
+/**
+ * Bundle an Express app as a serverless handler. Writes a temporary entry file
+ * to the user's cwd (for node_modules resolution), lazy-loads the bundled
+ * build tool, then cleans up.
+ *
+ * `express` is always external; additional externals can be passed via
+ * `BuildArgs.external`.
+ */
+declare function buildServerless(args: BuildArgs): Promise<void>;
+/**
+ * A platform-agnostic serverless handler function (the output of
+ * `build-serverless`).
+ */
+type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
+/**
+ * The result shape returned by `serverless-http` (and the `build` output).
+ */
+interface ServerlessResult {
+    statusCode?: number;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: string;
+    isBase64Encoded?: boolean;
+}
+/**
+ * Build a serverless event from HTTP request components.
+ *
+ * Exported for direct unit testing.
+ */
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): Record<string, unknown>;
+/**
+ * Write a serverless handler result to an Express response.
+ *
+ * Exported for direct unit testing.
+ */
+declare function applyServerlessResult(result: unknown, res: Response): void;
+/**
+ * Create an Express app that proxies all requests to a serverless handler.
+ * Each HTTP request is translated into a serverless event, the handler is
+ * invoked, and the result is written back to the response.
+ *
+ * Express body parsers are disabled; the raw request body is read directly
+ * from the stream and passed as a Buffer (so the serverless handler's request
+ * hook — including the #305 workaround — works identically to production).
+ */
+declare function createServerlessAdapterApp(handler: GenericHandler): Express;
+/**
+ * Load a bundled app module from the `build` output.
+ */
+declare function loadBuiltApp(appPath: string): Promise<{
+    app: Express;
+    init?: RuntimeModuleInit;
+}>;
+/**
+ * Load a bundled serverless handler from a JS/CJS module. The module must
+ * export a `handler` function (or use `default` export).
+ */
+declare function loadHandler(handlerPath: string): Promise<GenericHandler>;
+
+type RuntimeCliCommand = Exclude<ParsedArgs, null>;
+interface DevCommandRunner<TLoaded> {
+    load: (appPath: string) => Promise<TLoaded> | TLoaded;
+    start: (loaded: TLoaded, options: DevArgs['options'] & {
+        exitAfterShutdown: true;
+    }) => void;
+    watch?: (args: DevArgs) => void;
+}
+interface BuildEntryCommandOptions {
+    generateEntry: (appPath: string, initPath?: string) => string;
+    tempEntryFilename: string;
+    allowInit?: boolean;
+    initErrorMessage?: string;
+}
+declare function runDevCommand<TLoaded>(args: DevArgs, runner: DevCommandRunner<TLoaded>): Promise<void>;
+declare function runExpressDevCommand(args: DevArgs): Promise<void>;
+declare function runBuildEntryCommand(args: BuildArgs, options: BuildEntryCommandOptions): Promise<void>;
+declare function runCliCommand(parsedArgs: RuntimeCliCommand): Promise<void>;
+
+export { type BuildArgs, type BuildEntryCommandOptions, type BuildEntryContentArgs, CLI_VERSION, type DevArgs, type DevCommandRunner, type GenericHandler, type ParsedArgs, type RuntimeCliCommand, type RuntimeModuleInit, type ServerlessResult, type StartArgs, type StartServerlessArgs, type Subcommand, applyServerlessResult, buildBundleFromEntryContent, buildChildArgs, buildRuntime, buildServerless, createServerlessAdapterApp, extractExport, generateRuntimeEntry, generateServerlessEntry, isExpressApp, loadApp, loadBuiltApp, loadEnvFiles, loadHandler, parseArgs, parseEnvFile, preloadModules, printHelp, readValue, resolveExport, runBuildEntryCommand, runCliCommand, runDevCommand, runExpressDevCommand, runWithWatch, toServerlessEvent };