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

package/README.md

@@ -23,10 +23,12 @@ pnpm add @web-ts-toolkit/express-runtime express
 - `startLocalServer()` — `http.createServer` + `listen` with friendly
   `EADDRINUSE` / `EACCES` errors, optional graceful `SIGINT` / `SIGTERM`
   shutdown that drains in-flight requests, and a configurable timeout.
-- CLI binary with three subcommands:
+- CLI binary with five subcommands:
   - `dev` — run an Express app as a local dev server
-  - `build` — bundle the app as a serverless handler
-  - `start` — smoke-test the bundled handler locally by translating HTTP ↔ serverless events
+  - `build` — bundle the app as a local runtime module
+  - `start` — start the bundled local app module
+  - `build-serverless` — bundle the app as a serverless handler
+  - `start-serverless` — smoke-test the bundled handler locally by translating HTTP ↔ serverless events
 
 ## Quick Start
 
@@ -131,19 +133,19 @@ npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app
 > be placed at the top level of your app module since `dev` does not expose an
 > `init` hook.
 
-### CLI — build (serverless bundle)
+### CLI — build (local runtime bundle)
 
-The `build` command generates a temporary serverless entry that wraps the app
-with `createServerlessHandler`, then bundles it into a deployment-ready file:
+The `build` command generates a temporary runtime entry that re-exports the app
+and optional `init` hook, then bundles it into a local runtime file:
 
 ```sh
-npx wtt-express-runtime build ./src/app.ts --out-dir netlify/functions
+npx wtt-express-runtime build ./src/app.ts --out-dir dist
 ```
 
 With an optional init hook (DB connections, cache warmup, etc.):
 
 ```sh
-npx wtt-express-runtime build ./src/app.ts --init ./src/init.ts --out-dir netlify/functions
+npx wtt-express-runtime build ./src/app.ts --init ./src/init.ts --out-dir dist
 ```
 
 ```ts
@@ -153,29 +155,54 @@ export default async () => {
 };
 ```
 
-This produces `netlify/functions/handler.js` (configurable via `--out-name`)
-that exports a `handler` function compatible with Netlify, Vercel, AWS Lambda,
-and any platform that calls `(event, context)`.
+This produces `dist/app.js` (configurable via `--out-name`) that default-exports
+the Express app and, when `--init` is used, also exports `init` for the `start`
+command to run before listening.
 
 > `express` is always external; additional externals can be added via
 > `--external`.
 
-### CLI — start (run a bundled handler locally)
+### CLI — start (run a bundled app locally)
 
-The `start` command runs a bundled serverless handler locally by translating
-HTTP requests into serverless events and the handler's results back into HTTP
-responses — letting you smoke-test the exact `build` output without a
-serverless platform:
+The `start` command runs the `build` output locally with `startLocalServer()`:
 
 ```sh
 npx wtt-express-runtime build ./src/app.ts --out-dir dist
-npx wtt-express-runtime start ./dist/handler.js --port 9000 --env .env
+npx wtt-express-runtime start ./dist/app.js --port 9000 --env .env
+```
+
+The bundled app module must default-export an Express app (or export it as
+`app`). If it exports `init`, that hook runs once before the server starts
+listening.
+
+### CLI — build-serverless (serverless bundle)
+
+The `build-serverless` command preserves the previous serverless bundling flow:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --out-dir netlify/functions
 ```
 
-The handler module must export a `handler` function (named or default) that
-accepts `(event, context)` and returns a result with `statusCode`, `headers`,
-and `body` — the same shape produced by `createServerlessHandler` via
-`serverless-http`.
+With an optional init hook:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --init ./src/init.ts --out-dir netlify/functions
+```
+
+This produces `netlify/functions/handler.js` (configurable via `--out-name`)
+that exports a `handler` function compatible with Netlify, Vercel, AWS Lambda,
+and any platform that calls `(event, context)`.
+
+### CLI — start-serverless (run a bundled handler locally)
+
+The `start-serverless` command runs a bundled serverless handler locally by
+translating HTTP requests into serverless events and the handler's results back
+into HTTP responses:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --out-dir dist
+npx wtt-express-runtime start-serverless ./dist/handler.js --port 9000 --env .env
+```
 
 > The adapter passes the raw request body as a Buffer (no body parsing) so the
 > handler's request hook, including the serverless-http #305 workaround, runs
@@ -294,15 +321,19 @@ 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.
 
-| Command | Description                                                                         |
-| ------- | ----------------------------------------------------------------------------------- |
-| `dev`   | Run the Express app as a local dev server (`http.createServer` + graceful shutdown) |
-| `build` | Bundle the Express app as a serverless handler                                      |
-| `start` | Run a bundled serverless handler locally (HTTP ↔ serverless event adapter)          |
+| Command            | Description                                                                         |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `dev`              | Run the Express app as a local dev server (`http.createServer` + graceful shutdown) |
+| `build`            | Bundle the Express app as a local runtime module                                    |
+| `start`            | Run a bundled local app module with `startLocalServer()`                            |
+| `build-serverless` | Bundle the Express app as a serverless handler                                      |
+| `start-serverless` | Run a bundled serverless handler locally (HTTP ↔ serverless event adapter)          |
 
 #### dev options
 
@@ -326,7 +357,7 @@ Omitting `<command>` defaults to `dev` for backward compatibility.
 | `<app-module>`        | Module path whose **default export** is an Express app (sync, not async factory) |
 | `--init <path>`       | Init hook module (default export, async function) called once per cold start     |
 | `--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` is always external)              |
@@ -334,15 +365,40 @@ Omitting `<command>` defaults to `dev` for backward compatibility.
 
 #### start options
 
-| Option                    | Description                                                                                |
-| ------------------------- | ------------------------------------------------------------------------------------------ |
-| `<handler-module>`        | JS/CJS module path exporting `handler` (named or default) — the output of `build`          |
-| `--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 handler load (repeatable; comma-separated values supported)    |
-| `--env <path>`            | Env file(s) to load before handler load (repeatable; existing env vars are not overridden) |
+| Option                    | Description                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<app-module>`            | JS/CJS module path default-exporting an Express app (or exporting `app`) — the output of `build` |
+| `--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; comma-separated values supported)              |
+| `--env <path>`            | Env file(s) to load before app load (repeatable; existing env vars are not overridden)           |
+
+#### build-serverless options
+
+| Option                | Description                                                                      |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `<app-module>`        | Module path whose **default export** is an Express app (sync, not async factory) |
+| `--init <path>`       | Init hook module (default export, async function) called once per cold start     |
+| `--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` is always external)              |
+| `--no-clean`          | Don't clean the output directory before building                                 |
+
+#### start-serverless options
+
+| Option                    | Description                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------- |
+| `<handler-module>`        | JS/CJS module path exporting `handler` (named or default) — the output of `build-serverless` |
+| `--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 handler load (repeatable; comma-separated values supported)      |
+| `--env <path>`            | Env file(s) to load before handler load (repeatable; existing env vars are not overridden)   |
 
 #### global options
 
@@ -355,11 +411,12 @@ The `dev` command sets `exitAfterShutdown: true` so `SIGINT` / `SIGTERM` cleanly
 exit the process after the server drains. TypeScript app modules require a TS
 loader (see the Quick Start CLI section for a `tsx` invocation).
 
-The `build` command generates a temporary entry file that imports the app
-module and wraps it with `createServerlessHandler`, then produces a
-self-contained bundle. `express` is always external; all other dependencies
-(including `@web-ts-toolkit/express-runtime` and `serverless-http`) are
-bundled into the output unless marked external via `--external`.
+The `build` command generates a temporary entry file that re-exports the app
+module and optional `init` hook, then produces a local runtime bundle. The
+`build-serverless` command instead wraps the app with `createServerlessHandler`
+and bundles the serverless runtime. `express` is always external; all other
+dependencies are bundled into the output unless marked external via
+`--external`.
 
 ## License
 

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 };