@robodev-ai/runtime 0.1.0

package/src/deploy-files.ts

@@ -0,0 +1,529 @@
+export type DeployFile = {
+  path: string;
+  content: string;
+};
+
+export type FrontendKind = "react" | "static" | "none";
+
+export type FileClass = "api" | "frontend" | "static" | "config" | "rejected";
+
+export const MAX_FILE_COUNT = 400;
+/** Prompt workspaces persist Tiny (`packages/be`, `apps/fe`, `.rulesync`) plus edits. */
+export const MAX_WORKSPACE_FILE_COUNT = 2000;
+export const MAX_FILE_BYTES = 1024 * 1024;
+/** Hashed Vite JS and SPA fonts from a Tiny static upload can exceed 1MB. */
+export const MAX_STATIC_FILE_BYTES = 8 * 1024 * 1024;
+export const MAX_TREE_BYTES = 25 * 1024 * 1024;
+export const MAX_PATH_LENGTH = 240;
+export const MAX_PATH_DEPTH = 12;
+export const DEPLOY_BODY_LIMIT_BYTES = 30 * 1024 * 1024;
+
+export const BINARY_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+  ".bmp",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".otf",
+  ".wasm",
+  ".zip",
+  ".gz",
+  ".tgz",
+  ".7z",
+  ".pdf",
+  ".mp4",
+  ".webm",
+  ".mp3",
+]);
+
+/** SPA dist binaries allowed only under `public/**`. Still denied at any other path. */
+export const PUBLIC_BINARY_EXTENSIONS = new Set([
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+]);
+
+const SRC_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".css",
+  ".json",
+  ".svg",
+]);
+const PUBLIC_EXTENSIONS = new Set([...SRC_EXTENSIONS, ".html", ".txt", ".md"]);
+const ROOT_STATIC_EXTENSIONS = new Set([".html", ".css", ".js", ".mjs", ".svg", ".txt", ".md"]);
+
+const CONFIG_FILES = new Set([
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mts",
+  "vite.config.mjs",
+  "README.md",
+  ".gitignore",
+]);
+
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".robodev"]);
+
+export type DeployFileError = {
+  statusCode: number;
+  code: string;
+  message: string;
+  path?: string;
+};
+
+export class DeployValidationError extends Error {
+  statusCode: number;
+  code: string;
+  path?: string;
+
+  constructor(input: DeployFileError) {
+    super(input.message);
+    this.statusCode = input.statusCode;
+    this.code = input.code;
+    this.path = input.path;
+  }
+}
+
+export function normalizeDeployPath(filePath: string): string {
+  return filePath.replaceAll("\\", "/");
+}
+
+export function isUnsafeDeployPath(filePath: string): boolean {
+  return (
+    filePath.startsWith("/") ||
+    filePath.includes("..") ||
+    filePath.split("/").some((segment) => segment === "") ||
+    /^[A-Za-z]:/.test(filePath)
+  );
+}
+
+function extname(filePath: string): string {
+  const base = filePath.split("/").pop() ?? "";
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return "";
+  return base.slice(dot).toLowerCase();
+}
+
+export function formatLimitMb(bytes: number): string {
+  return `${Math.round(bytes / (1024 * 1024))}MB`;
+}
+
+export function isPublicBinaryPath(filePath: string): boolean {
+  return filePath.startsWith("public/") && PUBLIC_BINARY_EXTENSIONS.has(extname(filePath));
+}
+
+export function deployFileStoredBytes(file: { path: string; content: string }): number {
+  if (isPublicBinaryPath(file.path)) {
+    return Buffer.from(file.content, "base64").byteLength;
+  }
+  return Buffer.byteLength(file.content, "utf8");
+}
+
+function basename(filePath: string): string {
+  return filePath.split("/").pop() ?? filePath;
+}
+
+function isTsconfigName(name: string): boolean {
+  return name === "tsconfig.json" || /^tsconfig\..+\.json$/.test(name);
+}
+
+function isHiddenDenied(filePath: string): boolean {
+  const name = basename(filePath);
+  if (name === ".gitignore") return false;
+  return name.startsWith(".");
+}
+
+export const ROBODEV_PREFIX = "robodev/";
+export const ROBODEV_DATABASE_FILE = "robodev/database.ts";
+export const LEGACY_DATABASE_FILE = "database.ts";
+export const ROBODEV_PACKAGE_JSON = "robodev/package.json";
+
+export function stripRobodevPrefix(filePath: string): string {
+  const path = normalizeDeployPath(filePath);
+  return path.startsWith(ROBODEV_PREFIX) ? path.slice(ROBODEV_PREFIX.length) : path;
+}
+
+export function backendRootFromFiles(files: readonly { path: string }[]): "robodev" | "" {
+  return files.some((file) => normalizeDeployPath(file.path) === ROBODEV_DATABASE_FILE)
+    ? "robodev"
+    : "";
+}
+
+export function databaseFilePath(files: readonly { path: string }[]): string | undefined {
+  const paths = new Set(files.map((file) => normalizeDeployPath(file.path)));
+  if (paths.has(ROBODEV_DATABASE_FILE)) return ROBODEV_DATABASE_FILE;
+  if (paths.has(LEGACY_DATABASE_FILE)) return LEGACY_DATABASE_FILE;
+  return undefined;
+}
+
+export function mixedBackendLayoutError(paths: Iterable<string>): string | null {
+  const list = [...paths].map((path) => normalizeDeployPath(path));
+  const hasNewDb = list.includes(ROBODEV_DATABASE_FILE);
+  const hasLegacyDb = list.includes(LEGACY_DATABASE_FILE);
+  const hasLegacyApiJobs = list.some(
+    (path) => path.startsWith("api/") || path.startsWith("jobs/") || path.startsWith("sockets/"),
+  );
+  const hasNewApiJobs = list.some(
+    (path) =>
+      path.startsWith("robodev/api/") ||
+      path.startsWith("robodev/jobs/") ||
+      path.startsWith("robodev/sockets/"),
+  );
+  if (hasNewDb && (hasLegacyDb || hasLegacyApiJobs)) {
+    return "Do not mix robodev/ backend files with root database.ts, api/, or jobs/";
+  }
+  if (hasLegacyDb && (hasNewDb || hasNewApiJobs)) {
+    return "Do not mix robodev/ backend files with root database.ts, api/, or jobs/";
+  }
+  return null;
+}
+
+function isRobodevLockfile(filePath: string): boolean {
+  return (
+    filePath === "robodev/package-lock.json" ||
+    filePath === "robodev/pnpm-lock.yaml" ||
+    filePath === "robodev/yarn.lock" ||
+    filePath === "robodev/npm-shrinkwrap.json"
+  );
+}
+
+export function isDeniedPath(filePath: string): boolean {
+  const parts = filePath.split("/");
+  if (parts[0] && SKIP_DIRS.has(parts[0])) return true;
+  if (filePath === "apps" || filePath.startsWith("apps/")) return true;
+  if (filePath === ".robodev" || filePath.startsWith(".robodev/")) return true;
+  if (filePath === ".env" || filePath.startsWith(".env.")) return true;
+  if (isRobodevLockfile(filePath)) return true;
+  if (isHiddenDenied(filePath)) return true;
+  if (BINARY_EXTENSIONS.has(extname(filePath)) && !isPublicBinaryPath(filePath)) return true;
+  return false;
+}
+
+const WORKSPACE_HIDDEN_ALLOW = new Set([
+  ".gitignore",
+  ".rulesync",
+  ".config",
+  ".oxlintrc.json",
+  ".oxlint-base.json",
+]);
+const WORKSPACE_ROOT_FILES = new Set([
+  "ROBODEV.md",
+  "openapi.json",
+  "rulesync.jsonc",
+  "oxfmt.config.js",
+  ".oxlintrc.json",
+  ".oxlint-base.json",
+]);
+
+function isEnvWorkspacePath(filePath: string): boolean {
+  const parts = filePath.split("/");
+  return parts.some((part) => part === ".env" || part.startsWith(".env."));
+}
+
+export function isDeniedWorkspacePath(filePath: string): boolean {
+  const parts = filePath.split("/");
+  if (parts.some((part) => SKIP_DIRS.has(part))) return true;
+  if (filePath === ".robodev" || filePath.startsWith(".robodev/")) return true;
+  if (isEnvWorkspacePath(filePath)) return true;
+  if (isRobodevLockfile(filePath)) return true;
+  if (BINARY_EXTENSIONS.has(extname(filePath))) return true;
+  const name = basename(filePath);
+  if (name.startsWith(".")) {
+    if (WORKSPACE_HIDDEN_ALLOW.has(name) || WORKSPACE_HIDDEN_ALLOW.has(parts[0] ?? ""))
+      return false;
+    return true;
+  }
+  return false;
+}
+
+export function isAllowedWorkspacePath(filePath: string): boolean {
+  const path = normalizeDeployPath(filePath);
+  if (isUnsafeDeployPath(path) || isDeniedWorkspacePath(path)) return false;
+  if (path.startsWith("packages/be/")) return true;
+  if (path.startsWith("apps/fe/")) return true;
+  if (path.startsWith(".rulesync/")) return true;
+  if (path.startsWith(".config/")) return true;
+  if (WORKSPACE_ROOT_FILES.has(path)) return true;
+  return isAllowedDeployPath(path);
+}
+
+export function mapPackagesBePath(filePath: string): string | null {
+  const path = normalizeDeployPath(filePath);
+  if (path === "packages/be/database.ts") return LEGACY_DATABASE_FILE;
+  for (const prefix of [
+    "packages/be/api/",
+    "packages/be/jobs/",
+    "packages/be/hooks/",
+    "packages/be/sockets/",
+  ] as const) {
+    if (path.startsWith(prefix) && path.endsWith(".ts")) {
+      return path.slice("packages/be/".length);
+    }
+  }
+  return null;
+}
+
+export function mapWorkspaceToDeployFiles(
+  files: readonly { path: string; content: string }[],
+): DeployFile[] {
+  const out: DeployFile[] = [];
+  const seen = new Set<string>();
+  for (const file of files) {
+    const mapped = mapPackagesBePath(file.path);
+    const path = mapped ?? normalizeDeployPath(file.path);
+    if (!mapped && (isDeniedPath(path) || !isAllowedDeployPath(path))) continue;
+    if (seen.has(path)) continue;
+    seen.add(path);
+    out.push({ path, content: file.content });
+  }
+  return out;
+}
+
+export function workspaceHasTinyFrontend(files: readonly { path: string }[]): boolean {
+  return files.some((file) => {
+    const path = normalizeDeployPath(file.path);
+    return path === "apps/fe/package.json" || path === "apps/fe/index.html";
+  });
+}
+
+export function workspaceHasPublishableFrontend(
+  workspace: readonly { path: string; content: string }[],
+): boolean {
+  const mapped = mapWorkspaceToDeployFiles(workspace);
+  return mapped.some((file) => {
+    const path = normalizeDeployPath(file.path);
+    if (path !== "index.html") return false;
+    const cls = classifyDeployPath(path);
+    return cls === "frontend" || cls === "static";
+  });
+}
+
+export function workspaceHasFrontend(files: readonly { path: string; content: string }[]): boolean {
+  return workspaceHasTinyFrontend(files) || workspaceHasPublishableFrontend(files);
+}
+
+export function isConfigPath(filePath: string): boolean {
+  const name = basename(filePath);
+  if (CONFIG_FILES.has(filePath) || CONFIG_FILES.has(name)) return true;
+  if (isTsconfigName(name) && !filePath.includes("/")) return true;
+  return false;
+}
+
+/**
+ * `*.test.ts` / `*.spec.ts` under the backend tree are the project's own tests. They ship and
+ * stay editable, but are never bundled or routed: they import test-only modules such as
+ * `node:test` that the deployed handler tree has no reason to pull in.
+ */
+export function isBackendTestPath(filePath: string): boolean {
+  return /\.(test|spec)\.ts$/.test(normalizeDeployPath(filePath));
+}
+
+export function isApiPath(filePath: string): boolean {
+  const inner = stripRobodevPrefix(filePath);
+  return inner === "database.ts" || (inner.startsWith("api/") && inner.endsWith(".ts"));
+}
+
+export function isJobPath(filePath: string): boolean {
+  const inner = stripRobodevPrefix(filePath);
+  return inner.startsWith("jobs/") && inner.endsWith(".ts");
+}
+
+export function isHookPath(filePath: string): boolean {
+  const inner = stripRobodevPrefix(filePath);
+  return inner.startsWith("hooks/") && inner.endsWith(".ts");
+}
+
+export function isSocketPath(filePath: string): boolean {
+  const inner = stripRobodevPrefix(filePath);
+  return inner.startsWith("sockets/") && inner.endsWith(".ts");
+}
+
+export function isSrcPath(filePath: string): boolean {
+  return filePath.startsWith("src/") && SRC_EXTENSIONS.has(extname(filePath));
+}
+
+export function isPublicPath(filePath: string): boolean {
+  if (!filePath.startsWith("public/")) return false;
+  return (
+    PUBLIC_EXTENSIONS.has(extname(filePath)) || PUBLIC_BINARY_EXTENSIONS.has(extname(filePath))
+  );
+}
+
+export function isRootStaticPath(filePath: string): boolean {
+  if (filePath.includes("/")) return false;
+  if (isConfigPath(filePath)) return false;
+  return ROOT_STATIC_EXTENSIONS.has(extname(filePath));
+}
+
+export function isAllowedDeployPath(filePath: string): boolean {
+  if (isRobodevLockfile(filePath)) return false;
+  const inner = stripRobodevPrefix(filePath);
+  const nested = filePath.startsWith(ROBODEV_PREFIX);
+  if (
+    inner === "database.ts" &&
+    (filePath === LEGACY_DATABASE_FILE || filePath === ROBODEV_DATABASE_FILE)
+  ) {
+    return true;
+  }
+  if (inner.startsWith("api/")) return inner.endsWith(".ts") && !inner.slice(4).includes("\\");
+  if (inner.startsWith("jobs/")) return inner.endsWith(".ts") && !inner.slice(5).includes("\\");
+  if (inner.startsWith("hooks/")) return inner.endsWith(".ts") && !inner.slice(6).includes("\\");
+  if (inner.startsWith("sockets/")) return inner.endsWith(".ts") && !inner.slice(8).includes("\\");
+  if (filePath === ROBODEV_PACKAGE_JSON) return true;
+  if (nested) return false;
+  if (filePath === "index.html") return true;
+  if (filePath.startsWith("src/")) return SRC_EXTENSIONS.has(extname(filePath));
+  if (filePath.startsWith("public/")) {
+    return (
+      PUBLIC_EXTENSIONS.has(extname(filePath)) || PUBLIC_BINARY_EXTENSIONS.has(extname(filePath))
+    );
+  }
+  if (isConfigPath(filePath)) return true;
+  if (isRootStaticPath(filePath)) return true;
+  return false;
+}
+
+export function classifyDeployPath(filePath: string): FileClass {
+  if (isDeniedPath(filePath) || isUnsafeDeployPath(filePath) || !isAllowedDeployPath(filePath)) {
+    return "rejected";
+  }
+  if (
+    isApiPath(filePath) ||
+    isJobPath(filePath) ||
+    isHookPath(filePath) ||
+    isSocketPath(filePath)
+  ) {
+    return "api";
+  }
+  if (isConfigPath(filePath)) return "config";
+  if (filePath.startsWith("src/") || filePath === "index.html") return "frontend";
+  if (isPublicPath(filePath) || isRootStaticPath(filePath)) return "static";
+  return "rejected";
+}
+
+export function detectFrontendKind(files: readonly { path: string }[]): FrontendKind {
+  const paths = new Set(files.map((file) => normalizeDeployPath(file.path)));
+  if (!paths.has("index.html")) return "none";
+  if (
+    paths.has("src/main.tsx") ||
+    paths.has("src/main.ts") ||
+    paths.has("src/main.jsx") ||
+    paths.has("src/main.js")
+  ) {
+    return "react";
+  }
+  return "static";
+}
+
+export function reactEntryPath(files: readonly { path: string }[]): string | null {
+  const paths = new Set(files.map((file) => normalizeDeployPath(file.path)));
+  for (const entry of ["src/main.tsx", "src/main.ts", "src/main.jsx", "src/main.js"]) {
+    if (paths.has(entry)) return entry;
+  }
+  return null;
+}
+
+export function isServedStaticPath(filePath: string): boolean {
+  if (filePath === "index.html") return true;
+  return isPublicPath(filePath) || isRootStaticPath(filePath);
+}
+
+export function webServePath(filePath: string): string | null {
+  if (filePath === "index.html") return "index.html";
+  if (isRootStaticPath(filePath)) return filePath;
+  if (filePath.startsWith("public/")) return filePath.slice("public/".length);
+  return null;
+}
+
+function fail(code: string, message: string, path?: string): never {
+  throw new DeployValidationError({ statusCode: 400, code, message, path });
+}
+
+export function validateDeployFiles(input: { path: string; content: string }[]): DeployFile[] {
+  const files: DeployFile[] = [];
+  const seen = new Set<string>();
+  let totalBytes = 0;
+
+  if (input.length > MAX_FILE_COUNT) {
+    fail("too_many_files", `Deploy may include at most ${MAX_FILE_COUNT} files`);
+  }
+
+  for (const raw of input) {
+    const path = normalizeDeployPath(raw.path);
+    if (
+      isUnsafeDeployPath(path) ||
+      path.length > MAX_PATH_LENGTH ||
+      path.split("/").length > MAX_PATH_DEPTH
+    ) {
+      fail("invalid_file_path", `Invalid file path: ${path}`, path);
+    }
+    if (seen.has(path)) {
+      fail("invalid_file", `Duplicate file path: ${path}`, path);
+    }
+    seen.add(path);
+    if (isDeniedPath(path) || !isAllowedDeployPath(path)) {
+      fail("invalid_file", `File is not allowed: ${path}`, path);
+    }
+    const storedBytes = deployFileStoredBytes({ path, content: raw.content });
+    const payloadBytes = Buffer.byteLength(raw.content, "utf8");
+    const maxBytes =
+      isPublicPath(path) || isRootStaticPath(path) ? MAX_STATIC_FILE_BYTES : MAX_FILE_BYTES;
+    if (storedBytes > maxBytes) {
+      fail("file_too_large", `File must be under ${formatLimitMb(maxBytes)}: ${path}`, path);
+    }
+    totalBytes += payloadBytes;
+    if (totalBytes > MAX_TREE_BYTES) {
+      fail("tree_too_large", `Deploy tree must be under ${formatLimitMb(MAX_TREE_BYTES)}`);
+    }
+    files.push({ path, content: raw.content });
+  }
+
+  const mixed = mixedBackendLayoutError(files.map((file) => file.path));
+  if (mixed) {
+    fail("mixed_backend_layout", mixed);
+  }
+
+  if (!databaseFilePath(files)) {
+    throw new DeployValidationError({
+      statusCode: 400,
+      code: "database_required",
+      message: "database.ts is required",
+    });
+  }
+
+  return files;
+}
+
+export function apiCompilePaths(files: readonly DeployFile[]): string[] {
+  return files
+    .filter(
+      (file) =>
+        !isBackendTestPath(file.path) &&
+        (isApiPath(file.path) ||
+          isJobPath(file.path) ||
+          isHookPath(file.path) ||
+          isSocketPath(file.path)),
+    )
+    .map((file) => file.path);
+}

package/src/handler-response.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { encodeHandlerResult } from "./handler-response.js";
+
+test("plain object stays JSON 200", () => {
+  const encoded = encodeHandlerResult({ ok: true });
+  assert.equal(encoded.status, 200);
+  assert.equal(encoded.contentType, "application/json; charset=utf-8");
+  assert.deepEqual(encoded.payload, { ok: true });
+});
+
+test("envelope sets status, headers, and contentType", () => {
+  const encoded = encodeHandlerResult({
+    status: 201,
+    headers: { "x-one": "a", connection: "close", "content-type": "text/ignored" },
+    contentType: "text/plain; charset=utf-8",
+    body: "hello",
+  });
+  assert.equal(encoded.status, 201);
+  assert.equal(encoded.contentType, "text/plain; charset=utf-8");
+  assert.equal(encoded.payload, "hello");
+  assert.equal(encoded.headers["x-one"], "a");
+  assert.equal(encoded.headers.connection, undefined);
+  assert.equal(encoded.headers["content-type"], undefined);
+});
+
+test("string, Buffer, and base64 bodies encode as bytes or text", () => {
+  assert.equal(encodeHandlerResult({ body: "Ad astra" }).contentType, "text/plain; charset=utf-8");
+  const fromBuffer = encodeHandlerResult({ body: Buffer.from("abc") });
+  assert.equal(fromBuffer.contentType, "application/octet-stream");
+  assert.deepEqual(fromBuffer.payload, Buffer.from("abc"));
+  const fromBase64 = encodeHandlerResult({
+    body: { base64: Buffer.from("xyz").toString("base64") },
+  });
+  assert.deepEqual(fromBase64.payload, Buffer.from("xyz"));
+});
+
+test("extra key stays plain JSON", () => {
+  const encoded = encodeHandlerResult({ body: "x", extra: true });
+  assert.equal(encoded.status, 200);
+  assert.equal(encoded.contentType, "application/json; charset=utf-8");
+  assert.deepEqual(encoded.payload, { body: "x", extra: true });
+});

package/src/handler-response.ts

@@ -0,0 +1,95 @@
+const ENVELOPE_KEYS = new Set(["status", "headers", "contentType", "body"]);
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+export type EncodedHandlerResult = {
+  status: number;
+  headers: Record<string, string>;
+  contentType: string;
+  payload: unknown;
+};
+
+function isEnvelope(value: unknown): value is {
+  status?: unknown;
+  headers?: unknown;
+  contentType?: unknown;
+  body: unknown;
+} {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  if (!Object.hasOwn(value, "body")) return false;
+  return Object.keys(value).every((key) => ENVELOPE_KEYS.has(key));
+}
+
+function isHopByHop(name: string): boolean {
+  return HOP_BY_HOP.has(name.toLowerCase());
+}
+
+function encodeBody(
+  body: unknown,
+  contentType?: string,
+): {
+  contentType: string;
+  payload: unknown;
+} {
+  if (body instanceof Uint8Array) {
+    return {
+      contentType: contentType ?? "application/octet-stream",
+      payload: Buffer.isBuffer(body) ? body : Buffer.from(body),
+    };
+  }
+  if (
+    typeof body === "object" &&
+    body !== null &&
+    !Array.isArray(body) &&
+    Object.keys(body).length === 1 &&
+    typeof (body as { base64?: unknown }).base64 === "string"
+  ) {
+    return {
+      contentType: contentType ?? "application/octet-stream",
+      payload: Buffer.from((body as { base64: string }).base64, "base64"),
+    };
+  }
+  if (typeof body === "string") {
+    return {
+      contentType: contentType ?? "text/plain; charset=utf-8",
+      payload: body,
+    };
+  }
+  return {
+    contentType: contentType ?? "application/json; charset=utf-8",
+    payload: body,
+  };
+}
+
+export function encodeHandlerResult(value: unknown): EncodedHandlerResult {
+  if (!isEnvelope(value)) {
+    return {
+      status: 200,
+      headers: {},
+      contentType: "application/json; charset=utf-8",
+      payload: value,
+    };
+  }
+
+  const status =
+    typeof value.status === "number" && Number.isFinite(value.status) ? value.status : 200;
+  const headers: Record<string, string> = {};
+  if (value.headers && typeof value.headers === "object" && !Array.isArray(value.headers)) {
+    for (const [name, headerValue] of Object.entries(value.headers)) {
+      if (typeof headerValue !== "string" || isHopByHop(name)) continue;
+      if (name.toLowerCase() === "content-type") continue;
+      headers[name] = headerValue;
+    }
+  }
+  const contentType = typeof value.contentType === "string" ? value.contentType : undefined;
+  const encoded = encodeBody(value.body, contentType);
+  return { status, headers, ...encoded };
+}

package/src/handler-timeout.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  clampTimeoutMs,
+  DEFAULT_TIMEOUT_MS,
+  HandlerTimeoutError,
+  MAX_TIMEOUT_MS,
+  withHandlerTimeout,
+} from "./handler-timeout.js";
+
+test("defaults to 10000 and clamps to 30s", () => {
+  assert.equal(clampTimeoutMs(), DEFAULT_TIMEOUT_MS);
+  assert.equal(clampTimeoutMs(40_000), MAX_TIMEOUT_MS);
+  assert.equal(clampTimeoutMs(0), 1);
+  assert.equal(clampTimeoutMs(1500), 1500);
+});
+
+test("overdue handler rejects with handler_timeout", async () => {
+  await assert.rejects(
+    () => withHandlerTimeout(() => new Promise((resolve) => setTimeout(resolve, 50)), 10),
+    (error: unknown) => error instanceof HandlerTimeoutError && error.message === "handler_timeout",
+  );
+});