@web-ts-toolkit/express-runtime 0.40.1 → 0.42.0

package/cli-api.d.mts

@@ -1,15 +1,14 @@
-import { Response, Express } from 'express';
-import { LocalServerOptions } from './index.mjs';
+import { LocalServerOptions, LocalServer } from './index.mjs';
+import { watch, existsSync } from 'node:fs';
+import { ChildProcess, fork } from 'node:child_process';
+import { Response, Request, Express } from 'express';
 import 'node:http';
 import 'serverless-http';
 
+declare const CLI_VERSION: string;
 /**
- * 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.
+ * Read the next argv value after a flag, throwing if it is missing, empty, or
+ * looks like another flag.
  */
 declare function readValue(argv: string[], index: number, name: string): string;
 type Subcommand = 'dev' | 'build' | 'start' | 'build-serverless' | 'start-serverless';
@@ -42,7 +41,6 @@ interface BuildArgs {
 }
 interface BuildEntryContentArgs {
     entryContent: string;
-    tempEntryFilename: string;
     tsconfigPath?: string;
     outDir: string;
     outName: string;
@@ -62,6 +60,8 @@ interface StartArgs {
 interface StartServerlessArgs {
     handlerPath: string;
     options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Maximum bytes to buffer for request bodies via the local adapter. Default: 1048576. */
+    maxBodyBytes?: number;
     /** Modules to preload before loading the handler (repeatable `--require`). */
     require: string[];
     /** Env files to load before loading the handler (repeatable `--env`). */
@@ -107,7 +107,8 @@ 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.
+ * Public helper for packages that reuse the CLI's env-file parsing without
+ * shelling out to the binary.
  */
 declare function parseEnvFile(content: string): Record<string, string>;
 /**
@@ -115,7 +116,8 @@ declare function parseEnvFile(content: string): Record<string, string>;
  * **not** overridden (consistent with dotenv's default behavior). Missing
  * files throw with a friendly message.
  *
- * Exported for direct unit testing.
+ * Public helper for programmatic CLI integrations. Mutates `process.env` by
+ * design and never overwrites existing environment variables.
  */
 declare function loadEnvFiles(paths: string[]): void;
 /**
@@ -123,38 +125,90 @@ declare function loadEnvFiles(paths: string[]): void;
  * loading the app module. Each module is `require()`-ed, running its
  * side effects (registering hooks, loading configs, etc.).
  *
- * Exported for direct unit testing.
+ * Public helper for programmatic CLI integrations that need the same preload
+ * behavior as the binary before loading an app or handler module.
  */
 declare function preloadModules(modules: string[]): Promise<void>;
+/**
+ * Dependencies for watch supervision, injectable for tests.
+ * Not part of the documented public API; exposed for deterministic testing
+ * without expanding the supported consumer contract.
+ */
+interface WatchSupervisorDeps {
+    fork?: typeof fork;
+    watch?: typeof watch;
+    existsSync?: typeof existsSync;
+    logger?: Pick<Console, 'error'>;
+    killTimeoutMs?: number;
+    setTimeout?: typeof setTimeout;
+    clearTimeout?: typeof clearTimeout;
+    exit?: (code: number) => void;
+    installSignalHandlers?: boolean;
+}
+/**
+ * Controller returned by the injectable supervisor factory.
+ * Allows tests to observe and deterministically shut down watchers/children.
+ */
+interface WatchSupervisorController {
+    /** Stop watching and terminate child, idempotent. */
+    shutdown: () => Promise<void>;
+    /** Currently tracked child, if any. */
+    getChild: () => ChildProcess | null;
+    /** Active watchers (FSWatcher handles). */
+    getWatchers: () => ReturnType<typeof watch>[];
+    /** Whether shutdown has been initiated. */
+    isShuttingDown: () => boolean;
+}
 /**
  * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
  * flags (the child runs without watch mode).
  *
- * Exported for direct unit testing.
+ * Public helper for CLI wrappers that supervise watch mode themselves and need
+ * the same child argv reconstruction as `runWithWatch`.
  */
 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 }`.
+ * restarts the child (SIGTERM, then SIGKILL after 5 seconds) on changes
+ * matching the given extensions. Uses Node 20+'s `fs.watch` with
+ * `{ recursive: true }`.
+ *
+ * Production entry point that delegates to `createWatchSupervisor` with real
+ * dependencies and installs signal handlers that exit the process.
  */
-declare function runWithWatch(args: DevArgs): void;
+declare function runWithWatch(args: DevArgs, deps?: WatchSupervisorDeps): WatchSupervisorController;
+/** Legacy fixed staging filenames — no longer written, but retained for regression tests that verify they are not overwritten. */
+declare const TEMP_BUILD_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+declare const TEMP_SERVERLESS_ENTRY_FILENAME = ".express-runtime-build-serverless-entry.ts";
 type RuntimeModuleInit = () => Promise<void> | void;
+type RuntimeModuleShutdown = () => 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.
+ * Public build-entry generator used by programmatic CLI integrations.
  */
 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.
+ * Public build-entry generator used by programmatic CLI integrations.
  */
 declare function generateRuntimeEntry(appPath: string, initPath?: string): string;
+/**
+ * Validate that `outDir` is safe to clean before invoking tsup.
+ * Prevents destructive `clean: true` combinations:
+ *  - filesystem root
+ *  - project cwd itself (repository root)
+ *  - symlinked output directories
+ *  - output that contains input files (appPath/initPath)
+ *
+ * Public safety check for programmatic build integrations before invoking
+ * `buildBundleFromEntryContent()` with `clean: true`.
+ */
+declare function validateOutDirForClean(outDir: string, clean: boolean, appPath?: string, initPath?: string): void;
 declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
 /**
  * Bundle an Express app as a local runtime module. The output default-exports
@@ -175,25 +229,70 @@ declare function buildServerless(args: BuildArgs): Promise<void>;
  * `build-serverless`).
  */
 type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
+/** AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter. */
+interface ApiGatewayRestEvent {
+    httpMethod: string;
+    path: string;
+    headers: Record<string, string>;
+    multiValueHeaders: Record<string, string[]>;
+    queryStringParameters: Record<string, string> | null;
+    multiValueQueryStringParameters: Record<string, string[]> | null;
+    body: string;
+    isBase64Encoded: boolean;
+    requestContext: {
+        identity: {
+            sourceIp: string;
+        };
+    };
+}
 /**
- * The result shape returned by `serverless-http` (and the `build` output).
+ * AWS API Gateway REST API v1 / Lambda proxy result shape returned by `serverless-http`.
  */
 interface ServerlessResult {
     statusCode?: number;
-    headers?: Record<string, string | string[] | undefined>;
+    headers?: Record<string, string | undefined>;
+    multiValueHeaders?: Record<string, string[] | undefined>;
     body?: string;
     isBase64Encoded?: boolean;
 }
+declare const DEFAULT_ADAPTER_MAX_BODY_BYTES: number;
+interface ServerlessAdapterOptions {
+    /**
+     * Maximum bytes to buffer for a single request body.
+     * Default: 1048576 (1 MiB). Must be a finite non-negative integer.
+     * When `0`, no body is allowed — any non-empty body receives `413`.
+     * The adapter never retains more than this limit plus at most one incoming chunk.
+     */
+    maxBodyBytes?: number;
+}
+/**
+ * Validate `maxBodyBytes` — finite non-negative integer. Zero means no body allowed (empty bodies only).
+ * Public validator shared by CLI parsing and programmatic adapter callers.
+ */
+declare function validateMaxBodyBytes(value: unknown): number;
+/**
+ * Read the raw request body into a Buffer with bounded memory.
+ * Since `createExpressApp` is called with `json: false, urlencoded: false` in the adapter,
+ * no body parser has consumed the stream yet. Rejects oversized declared or incremental
+ * bodies with a `LIMIT_EXCEEDED` error (413), stops retaining chunks after the limit,
+ * removes owned listeners, and drains the request.
+ * Distinguishes client aborts (`CLIENT_ABORT`) and stream errors from oversize.
+ */
+declare function collectBody(req: Request, maxBytes: number): Promise<Buffer>;
 /**
- * Build a serverless event from HTTP request components.
+ * Build an AWS API Gateway REST API v1 / Lambda proxy event from HTTP request components.
  *
- * Exported for direct unit testing.
+ * Public helper for adapters that need the same AWS REST API v1 event shape as
+ * the `start-serverless` command.
  */
-declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): Record<string, unknown>;
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): ApiGatewayRestEvent;
 /**
  * Write a serverless handler result to an Express response.
+ * Validates the complete AWS API Gateway REST API v1 / Lambda proxy result before writing anything.
+ * `multiValueHeaders` wins over `headers` when the same header appears in both maps.
  *
- * Exported for direct unit testing.
+ * Public helper for adapters that need the same AWS REST API v1 result-to-HTTP
+ * translation as the `start-serverless` command.
  */
 declare function applyServerlessResult(result: unknown, res: Response): void;
 /**
@@ -204,14 +303,18 @@ declare function applyServerlessResult(result: unknown, res: Response): void;
  * 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).
+ * Bodies exceeding `maxBodyBytes` (default 1 MiB, 0 = empty bodies only) receive
+ * `413 Payload Too Large` without invoking the handler; the request is drained
+ * and retained memory is bounded to the limit plus at most one chunk.
  */
-declare function createServerlessAdapterApp(handler: GenericHandler): Express;
+declare function createServerlessAdapterApp(handler: GenericHandler, options?: ServerlessAdapterOptions): Express;
 /**
  * Load a bundled app module from the `build` output.
  */
 declare function loadBuiltApp(appPath: string): Promise<{
     app: Express;
     init?: RuntimeModuleInit;
+    shutdown?: RuntimeModuleShutdown;
 }>;
 /**
  * Load a bundled serverless handler from a JS/CJS module. The module must
@@ -224,12 +327,13 @@ interface DevCommandRunner<TLoaded> {
     load: (appPath: string) => Promise<TLoaded> | TLoaded;
     start: (loaded: TLoaded, options: DevArgs['options'] & {
         exitAfterShutdown: true;
-    }) => void;
-    watch?: (args: DevArgs) => void;
+    }) => LocalServer | void;
+    watch?: (args: DevArgs) => void | WatchSupervisorController;
 }
 interface BuildEntryCommandOptions {
     generateEntry: (appPath: string, initPath?: string) => string;
-    tempEntryFilename: string;
+    /** @deprecated staging is now uniquely created; this is ignored if provided */
+    tempEntryFilename?: string;
     allowInit?: boolean;
     initErrorMessage?: string;
 }
@@ -238,4 +342,4 @@ 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 };
+export { type ApiGatewayRestEvent, type BuildArgs, type BuildEntryCommandOptions, type BuildEntryContentArgs, CLI_VERSION, DEFAULT_ADAPTER_MAX_BODY_BYTES, type DevArgs, type DevCommandRunner, type GenericHandler, type ParsedArgs, type RuntimeCliCommand, type RuntimeModuleInit, type RuntimeModuleShutdown, type ServerlessAdapterOptions, type ServerlessResult, type StartArgs, type StartServerlessArgs, type Subcommand, TEMP_BUILD_ENTRY_FILENAME, TEMP_SERVERLESS_ENTRY_FILENAME, applyServerlessResult, buildBundleFromEntryContent, buildChildArgs, buildRuntime, buildServerless, collectBody, createServerlessAdapterApp, extractExport, generateRuntimeEntry, generateServerlessEntry, isExpressApp, loadApp, loadBuiltApp, loadEnvFiles, loadHandler, parseArgs, parseEnvFile, preloadModules, printHelp, readValue, resolveExport, runBuildEntryCommand, runCliCommand, runDevCommand, runExpressDevCommand, runWithWatch, toServerlessEvent, validateMaxBodyBytes, validateOutDirForClean };

package/cli-api.d.ts

@@ -1,15 +1,14 @@
-import { Response, Express } from 'express';
-import { LocalServerOptions } from './index.js';
+import { LocalServerOptions, LocalServer } from './index.js';
+import { watch, existsSync } from 'node:fs';
+import { ChildProcess, fork } from 'node:child_process';
+import { Response, Request, Express } from 'express';
 import 'node:http';
 import 'serverless-http';
 
+declare const CLI_VERSION: string;
 /**
- * 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.
+ * Read the next argv value after a flag, throwing if it is missing, empty, or
+ * looks like another flag.
  */
 declare function readValue(argv: string[], index: number, name: string): string;
 type Subcommand = 'dev' | 'build' | 'start' | 'build-serverless' | 'start-serverless';
@@ -42,7 +41,6 @@ interface BuildArgs {
 }
 interface BuildEntryContentArgs {
     entryContent: string;
-    tempEntryFilename: string;
     tsconfigPath?: string;
     outDir: string;
     outName: string;
@@ -62,6 +60,8 @@ interface StartArgs {
 interface StartServerlessArgs {
     handlerPath: string;
     options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Maximum bytes to buffer for request bodies via the local adapter. Default: 1048576. */
+    maxBodyBytes?: number;
     /** Modules to preload before loading the handler (repeatable `--require`). */
     require: string[];
     /** Env files to load before loading the handler (repeatable `--env`). */
@@ -107,7 +107,8 @@ 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.
+ * Public helper for packages that reuse the CLI's env-file parsing without
+ * shelling out to the binary.
  */
 declare function parseEnvFile(content: string): Record<string, string>;
 /**
@@ -115,7 +116,8 @@ declare function parseEnvFile(content: string): Record<string, string>;
  * **not** overridden (consistent with dotenv's default behavior). Missing
  * files throw with a friendly message.
  *
- * Exported for direct unit testing.
+ * Public helper for programmatic CLI integrations. Mutates `process.env` by
+ * design and never overwrites existing environment variables.
  */
 declare function loadEnvFiles(paths: string[]): void;
 /**
@@ -123,38 +125,90 @@ declare function loadEnvFiles(paths: string[]): void;
  * loading the app module. Each module is `require()`-ed, running its
  * side effects (registering hooks, loading configs, etc.).
  *
- * Exported for direct unit testing.
+ * Public helper for programmatic CLI integrations that need the same preload
+ * behavior as the binary before loading an app or handler module.
  */
 declare function preloadModules(modules: string[]): Promise<void>;
+/**
+ * Dependencies for watch supervision, injectable for tests.
+ * Not part of the documented public API; exposed for deterministic testing
+ * without expanding the supported consumer contract.
+ */
+interface WatchSupervisorDeps {
+    fork?: typeof fork;
+    watch?: typeof watch;
+    existsSync?: typeof existsSync;
+    logger?: Pick<Console, 'error'>;
+    killTimeoutMs?: number;
+    setTimeout?: typeof setTimeout;
+    clearTimeout?: typeof clearTimeout;
+    exit?: (code: number) => void;
+    installSignalHandlers?: boolean;
+}
+/**
+ * Controller returned by the injectable supervisor factory.
+ * Allows tests to observe and deterministically shut down watchers/children.
+ */
+interface WatchSupervisorController {
+    /** Stop watching and terminate child, idempotent. */
+    shutdown: () => Promise<void>;
+    /** Currently tracked child, if any. */
+    getChild: () => ChildProcess | null;
+    /** Active watchers (FSWatcher handles). */
+    getWatchers: () => ReturnType<typeof watch>[];
+    /** Whether shutdown has been initiated. */
+    isShuttingDown: () => boolean;
+}
 /**
  * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
  * flags (the child runs without watch mode).
  *
- * Exported for direct unit testing.
+ * Public helper for CLI wrappers that supervise watch mode themselves and need
+ * the same child argv reconstruction as `runWithWatch`.
  */
 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 }`.
+ * restarts the child (SIGTERM, then SIGKILL after 5 seconds) on changes
+ * matching the given extensions. Uses Node 20+'s `fs.watch` with
+ * `{ recursive: true }`.
+ *
+ * Production entry point that delegates to `createWatchSupervisor` with real
+ * dependencies and installs signal handlers that exit the process.
  */
-declare function runWithWatch(args: DevArgs): void;
+declare function runWithWatch(args: DevArgs, deps?: WatchSupervisorDeps): WatchSupervisorController;
+/** Legacy fixed staging filenames — no longer written, but retained for regression tests that verify they are not overwritten. */
+declare const TEMP_BUILD_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+declare const TEMP_SERVERLESS_ENTRY_FILENAME = ".express-runtime-build-serverless-entry.ts";
 type RuntimeModuleInit = () => Promise<void> | void;
+type RuntimeModuleShutdown = () => 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.
+ * Public build-entry generator used by programmatic CLI integrations.
  */
 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.
+ * Public build-entry generator used by programmatic CLI integrations.
  */
 declare function generateRuntimeEntry(appPath: string, initPath?: string): string;
+/**
+ * Validate that `outDir` is safe to clean before invoking tsup.
+ * Prevents destructive `clean: true` combinations:
+ *  - filesystem root
+ *  - project cwd itself (repository root)
+ *  - symlinked output directories
+ *  - output that contains input files (appPath/initPath)
+ *
+ * Public safety check for programmatic build integrations before invoking
+ * `buildBundleFromEntryContent()` with `clean: true`.
+ */
+declare function validateOutDirForClean(outDir: string, clean: boolean, appPath?: string, initPath?: string): void;
 declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
 /**
  * Bundle an Express app as a local runtime module. The output default-exports
@@ -175,25 +229,70 @@ declare function buildServerless(args: BuildArgs): Promise<void>;
  * `build-serverless`).
  */
 type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
+/** AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter. */
+interface ApiGatewayRestEvent {
+    httpMethod: string;
+    path: string;
+    headers: Record<string, string>;
+    multiValueHeaders: Record<string, string[]>;
+    queryStringParameters: Record<string, string> | null;
+    multiValueQueryStringParameters: Record<string, string[]> | null;
+    body: string;
+    isBase64Encoded: boolean;
+    requestContext: {
+        identity: {
+            sourceIp: string;
+        };
+    };
+}
 /**
- * The result shape returned by `serverless-http` (and the `build` output).
+ * AWS API Gateway REST API v1 / Lambda proxy result shape returned by `serverless-http`.
  */
 interface ServerlessResult {
     statusCode?: number;
-    headers?: Record<string, string | string[] | undefined>;
+    headers?: Record<string, string | undefined>;
+    multiValueHeaders?: Record<string, string[] | undefined>;
     body?: string;
     isBase64Encoded?: boolean;
 }
+declare const DEFAULT_ADAPTER_MAX_BODY_BYTES: number;
+interface ServerlessAdapterOptions {
+    /**
+     * Maximum bytes to buffer for a single request body.
+     * Default: 1048576 (1 MiB). Must be a finite non-negative integer.
+     * When `0`, no body is allowed — any non-empty body receives `413`.
+     * The adapter never retains more than this limit plus at most one incoming chunk.
+     */
+    maxBodyBytes?: number;
+}
+/**
+ * Validate `maxBodyBytes` — finite non-negative integer. Zero means no body allowed (empty bodies only).
+ * Public validator shared by CLI parsing and programmatic adapter callers.
+ */
+declare function validateMaxBodyBytes(value: unknown): number;
+/**
+ * Read the raw request body into a Buffer with bounded memory.
+ * Since `createExpressApp` is called with `json: false, urlencoded: false` in the adapter,
+ * no body parser has consumed the stream yet. Rejects oversized declared or incremental
+ * bodies with a `LIMIT_EXCEEDED` error (413), stops retaining chunks after the limit,
+ * removes owned listeners, and drains the request.
+ * Distinguishes client aborts (`CLIENT_ABORT`) and stream errors from oversize.
+ */
+declare function collectBody(req: Request, maxBytes: number): Promise<Buffer>;
 /**
- * Build a serverless event from HTTP request components.
+ * Build an AWS API Gateway REST API v1 / Lambda proxy event from HTTP request components.
  *
- * Exported for direct unit testing.
+ * Public helper for adapters that need the same AWS REST API v1 event shape as
+ * the `start-serverless` command.
  */
-declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): Record<string, unknown>;
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): ApiGatewayRestEvent;
 /**
  * Write a serverless handler result to an Express response.
+ * Validates the complete AWS API Gateway REST API v1 / Lambda proxy result before writing anything.
+ * `multiValueHeaders` wins over `headers` when the same header appears in both maps.
  *
- * Exported for direct unit testing.
+ * Public helper for adapters that need the same AWS REST API v1 result-to-HTTP
+ * translation as the `start-serverless` command.
  */
 declare function applyServerlessResult(result: unknown, res: Response): void;
 /**
@@ -204,14 +303,18 @@ declare function applyServerlessResult(result: unknown, res: Response): void;
  * 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).
+ * Bodies exceeding `maxBodyBytes` (default 1 MiB, 0 = empty bodies only) receive
+ * `413 Payload Too Large` without invoking the handler; the request is drained
+ * and retained memory is bounded to the limit plus at most one chunk.
  */
-declare function createServerlessAdapterApp(handler: GenericHandler): Express;
+declare function createServerlessAdapterApp(handler: GenericHandler, options?: ServerlessAdapterOptions): Express;
 /**
  * Load a bundled app module from the `build` output.
  */
 declare function loadBuiltApp(appPath: string): Promise<{
     app: Express;
     init?: RuntimeModuleInit;
+    shutdown?: RuntimeModuleShutdown;
 }>;
 /**
  * Load a bundled serverless handler from a JS/CJS module. The module must
@@ -224,12 +327,13 @@ interface DevCommandRunner<TLoaded> {
     load: (appPath: string) => Promise<TLoaded> | TLoaded;
     start: (loaded: TLoaded, options: DevArgs['options'] & {
         exitAfterShutdown: true;
-    }) => void;
-    watch?: (args: DevArgs) => void;
+    }) => LocalServer | void;
+    watch?: (args: DevArgs) => void | WatchSupervisorController;
 }
 interface BuildEntryCommandOptions {
     generateEntry: (appPath: string, initPath?: string) => string;
-    tempEntryFilename: string;
+    /** @deprecated staging is now uniquely created; this is ignored if provided */
+    tempEntryFilename?: string;
     allowInit?: boolean;
     initErrorMessage?: string;
 }
@@ -238,4 +342,4 @@ 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 };
+export { type ApiGatewayRestEvent, type BuildArgs, type BuildEntryCommandOptions, type BuildEntryContentArgs, CLI_VERSION, DEFAULT_ADAPTER_MAX_BODY_BYTES, type DevArgs, type DevCommandRunner, type GenericHandler, type ParsedArgs, type RuntimeCliCommand, type RuntimeModuleInit, type RuntimeModuleShutdown, type ServerlessAdapterOptions, type ServerlessResult, type StartArgs, type StartServerlessArgs, type Subcommand, TEMP_BUILD_ENTRY_FILENAME, TEMP_SERVERLESS_ENTRY_FILENAME, applyServerlessResult, buildBundleFromEntryContent, buildChildArgs, buildRuntime, buildServerless, collectBody, createServerlessAdapterApp, extractExport, generateRuntimeEntry, generateServerlessEntry, isExpressApp, loadApp, loadBuiltApp, loadEnvFiles, loadHandler, parseArgs, parseEnvFile, preloadModules, printHelp, readValue, resolveExport, runBuildEntryCommand, runCliCommand, runDevCommand, runExpressDevCommand, runWithWatch, toServerlessEvent, validateMaxBodyBytes, validateOutDirForClean };