feat: netlify runner

Author: pi0

AGENTS.md

@@ -30,9 +30,12 @@ src/
 │   │   └── runner.ts        # SelfEnvRunner (in-process, no worker)
 │   ├── miniflare/
 │   │   └── runner.ts        # MiniflareEnvRunner (Cloudflare Workers via miniflare)
-│   └── vercel/
-│       ├── runner.ts        # VercelEnvRunner (extends NodeWorkerEnvRunner)
-│       └── worker.ts        # Sets Vercel request context symbol, delegates to node-worker
+│   ├── vercel/
+│   │   ├── runner.ts        # VercelEnvRunner (extends NodeWorkerEnvRunner)
+│   │   └── worker.ts        # Sets Vercel request context symbol, delegates to node-worker
+│   └── netlify/
+│       ├── runner.ts        # NetlifyEnvRunner (extends NodeWorkerEnvRunner)
+│       └── worker.ts        # Sets global Netlify context, delegates to node-worker
 ├── types.ts                 # Core interfaces
 ├── index.ts                 # Public API exports
 ├── loader.ts                # Dynamic runner loader
@@ -57,7 +60,9 @@ src/
 - **`src/runners/miniflare/runner.ts`** — `MiniflareEnvRunner` extends `BaseEnvRunner`: runs entry in Cloudflare Workers runtime via miniflare. Overrides `fetch()` to use `mf.dispatchFetch()`. Uses in-memory `script` (no temp files), `unsafeModuleFallbackService` for module resolution, and `unsafeEvalBinding` for hot-reload via `reloadModule()`. Requires `miniflare` peer dependency
 - **`src/runners/vercel/runner.ts`** — `VercelEnvRunner` extends `NodeWorkerEnvRunner`: simulates Vercel deployment environment with header injection
 - **`src/runners/vercel/worker.ts`** — Sets `Symbol.for("@vercel/request-context")` on globalThis, delegates to node-worker worker
-- **`src/loader.ts`** — `loadRunner(name, opts)`: dynamic loader that imports a runner by name (`node-worker` | `node-process` | `bun-process` | `deno-process` | `self` | `miniflare` | `vercel`) and returns an `EnvRunner` instance
+- **`src/runners/netlify/runner.ts`** — `NetlifyEnvRunner` extends `NodeWorkerEnvRunner`: simulates Netlify deployment environment with header injection (`x-nf-client-connection-ip`, `x-nf-account-id`, `x-nf-site-id`, `x-nf-deploy-id`, `x-nf-deploy-context`, `x-nf-geo`, `x-nf-request-id`)
+- **`src/runners/netlify/worker.ts`** — Uses `@netlify/runtime` `startRuntime()` when available (sets up `globalThis.Netlify` with env/context and `globalThis.caches`), falls back to lightweight shim. Delegates to node-worker worker
+- **`src/loader.ts`** — `loadRunner(name, opts)`: dynamic loader that imports a runner by name (`node-worker` | `node-process` | `bun-process` | `deno-process` | `self` | `miniflare` | `vercel` | `netlify`) and returns an `EnvRunner` instance
 - **`src/manager.ts`** — `RunnerManager`: proxy manager for hot-reload, message queueing, and listener forwarding across runner swaps
 - **`src/server.ts`** — `EnvServer` extends `RunnerManager`: high-level API combining runner loading, watch mode (`fs.watch` with 100ms debounce), and auto-reload on file changes. Supports `watch` and `watchPaths` options
 - **`src/cli.ts`** — CLI entry point: `env-runner <entry> [--runner] [--port] [--host] [-w/--watch]`
@@ -127,6 +132,25 @@ Extends `NodeWorkerEnvRunner` to simulate a Vercel deployment environment. The w
 
 All headers are only injected when not already present in the request.
 
+### NetlifyEnvRunner
+
+Extends `NodeWorkerEnvRunner` to simulate a Netlify deployment environment. The worker sets `globalThis.Netlify` with `context` (null) and `env` (backed by `process.env`) for Netlify Functions API compatibility, then delegates to the node-worker worker.
+
+**Header injection:** Overrides `fetch()` to inject Netlify-specific headers before delegating to the parent:
+
+- `x-nf-client-connection-ip` — derived from `x-forwarded-for` (first IP) or `x-real-ip`, defaults to `127.0.0.1`
+- `x-nf-account-id` — defaults to `"0"`
+- `x-nf-site-id` — defaults to `"0"`
+- `x-nf-deploy-id` — defaults to `"0"`
+- `x-nf-deploy-context` — defaults to `"dev"`
+- `x-nf-geo` — base64-encoded JSON geolocation object, defaults to `{ city: "localhost", country: { code: "dev" } }`
+- `x-nf-request-id` — unique UUID per request via `crypto.randomUUID()`
+- `x-forwarded-for`, `x-real-ip` — set to client IP if not already present
+- `x-forwarded-proto` — protocol from request URL
+- `x-forwarded-host` — from `host` header or request URL
+
+All headers are only injected when not already present in the request.
+
 ### RunnerManager
 
 Proxy manager wrapping a runner with hot-reload support:
@@ -223,6 +247,7 @@ const runner2 = new NodeProcessEnvRunner({
 | _(no worker)_                                      | `SelfEnvRunner`        |
 | _(in-memory wrapper module)_                       | `MiniflareEnvRunner`   |
 | `env-runner/runners/vercel/worker` (default)       | `VercelEnvRunner`      |
+| `env-runner/runners/netlify/worker` (default)      | `NetlifyEnvRunner`     |
 
 ## Exports
 
@@ -239,12 +264,14 @@ const runner2 = new NodeProcessEnvRunner({
 - `env-runner/runners/miniflare` (`./runners/miniflare`) — Direct import of `MiniflareEnvRunner`
 - `env-runner/runners/vercel` (`./runners/vercel`) — Direct import of `VercelEnvRunner`
 - `env-runner/runners/vercel/worker` (`./runners/vercel/worker`) — Vercel worker (sets request context, delegates to node-worker)
+- `env-runner/runners/netlify` (`./runners/netlify`) — Direct import of `NetlifyEnvRunner`
+- `env-runner/runners/netlify/worker` (`./runners/netlify/worker`) — Netlify worker (sets global Netlify context, delegates to node-worker)
 - `env-runner/vite` (`./vite`) — Vite Environment API helpers (`createViteHotChannel`, `createViteTransport`)
 
 ## Testing
 
 - Tests use vitest: `pnpm vitest run`
-- **`test/runners.test.ts`** — Parameterized test suite for all IPC-based runner implementations (NodeWorker, NodeProcess, BunProcess, DenoProcess, Vercel). Runners requiring specific runtimes (bun, deno) are auto-skipped when the runtime is not available
+- **`test/runners.test.ts`** — Parameterized test suite for all IPC-based runner implementations (NodeWorker, NodeProcess, BunProcess, DenoProcess, Vercel, Netlify). Runners requiring specific runtimes (bun, deno) are auto-skipped when the runtime is not available
 - **`test/manager.test.ts`** — Tests for `RunnerManager` lifecycle, hot-reload, message queueing, hook forwarding
 - **`test/miniflare.test.ts`** — Tests for `MiniflareEnvRunner`: Durable Object exports, IPC alongside custom exports, hot-reload via `reloadModule()`, IPC re-initialization after reload
 - **`test/vite.test.ts`** — Tests for Vite helpers: `createViteHotChannel` message namespacing/filtering/on/off, `createViteTransport` connect/send filtering
@@ -255,7 +282,8 @@ const runner2 = new NodeProcessEnvRunner({
 - Test fixture in `test/fixtures/app-websocket.mjs` — Entry with crossws WebSocket hooks for websocket tests
 - Test fixture in `test/fixtures/app-headers.mjs` — Entry that echoes all request headers as JSON for vercel header injection tests
 - **`test/vercel.test.ts`** — Tests for `VercelEnvRunner`: header injection (`x-vercel-deployment-url`, `x-vercel-forwarded-for`, `x-forwarded-for`, `x-real-ip`, `x-forwarded-proto`, `x-forwarded-host`), header preservation, pre-existing header respect
-- Tests cover: lifecycle, fetch (GET/POST), WebSocket upgrade, crossws websocket, messaging, hooks, graceful close, inspect output, manager hot-reload, message queueing, miniflare hot-reload, vercel header injection, waitForReady, vite helpers
+- **`test/netlify.test.ts`** — Tests for `NetlifyEnvRunner`: header injection (`x-nf-client-connection-ip`, `x-nf-account-id`, `x-nf-site-id`, `x-nf-deploy-id`, `x-nf-deploy-context`, `x-nf-geo`, `x-nf-request-id`), IP derivation, header preservation
+- Tests cover: lifecycle, fetch (GET/POST), WebSocket upgrade, crossws websocket, messaging, hooks, graceful close, inspect output, manager hot-reload, message queueing, miniflare hot-reload, vercel header injection, netlify header injection, waitForReady, vite helpers
 
 ## Scripts
 
@@ -273,6 +301,7 @@ const runner2 = new NodeProcessEnvRunner({
 - `httpxy` — HTTP/WebSocket proxy
 - `srvx` — Universal server framework (used by built-in workers)
 - `miniflare` — Cloudflare Workers simulator (optional peer dependency, required for `MiniflareEnvRunner`)
+- `@netlify/runtime` — Netlify compute runtime (optional peer dependency, used by `NetlifyEnvRunner` worker for full `globalThis.Netlify` + `globalThis.caches` setup)
 
 > **See also:** [`.agents/MINIFLARE.md`](.agents/MINIFLARE.md) — Miniflare internals, `unsafeEvalBinding`, `unsafeModuleFallbackService`, service bindings patterns
 > **See also:** [`.agents/PLAN.vite-compat.md`](.agents/PLAN.vite-compat.md) — Planned improvements for Vite Environment API compatibility (`waitForReady`, RPC, transport helpers)

README.md

@@ -7,7 +7,7 @@
 
 <!-- /automd -->
 
-Generic environment runner for JavaScript runtimes. Run your server apps across Node.js worker threads, child processes, Bun, Deno, Cloudflare Workers (via miniflare), or in-process — with hot-reload, WebSocket proxying, and bidirectional messaging.
+Generic environment runner for JavaScript runtimes. Run your server apps across Node.js worker threads, child processes, Bun, Deno, Cloudflare Workers (via miniflare), Vercel, Netlify, or in-process — with hot-reload, WebSocket proxying, and bidirectional messaging.
 
 ## Usage
 
@@ -120,6 +120,8 @@ import { BunProcessEnvRunner } from "env-runner/runners/bun-process";
 import { DenoProcessEnvRunner } from "env-runner/runners/deno-process";
 import { SelfEnvRunner } from "env-runner/runners/self";
 import { MiniflareEnvRunner } from "env-runner/runners/miniflare";
+import { VercelEnvRunner } from "env-runner/runners/vercel";
+import { NetlifyEnvRunner } from "env-runner/runners/netlify";
 ```
 
 All runners implement the [`EnvRunner`](./src/types.ts) interface:
@@ -160,14 +162,16 @@ await runner.close();
 
 **Available runners:**
 
-| Runner                 | Isolation                      | IPC mechanism                      |
-| ---------------------- | ------------------------------ | ---------------------------------- |
-| `NodeWorkerEnvRunner`  | Worker thread                  | `workerData` / `parentPort`        |
-| `NodeProcessEnvRunner` | Child process (`fork`)         | `ENV_RUNNER_DATA` / `process.send` |
-| `BunProcessEnvRunner`  | Bun or Node.js process         | `Bun.spawn` IPC or `fork()`        |
-| `DenoProcessEnvRunner` | Deno process                   | `deno run` with IPC channel        |
-| `SelfEnvRunner`        | In-process                     | In-memory channel                  |
-| `MiniflareEnvRunner`   | Cloudflare Workers (miniflare) | WebSocket pair via `dispatchFetch` |
+| Runner                 | Isolation                       | IPC mechanism                      |
+| ---------------------- | ------------------------------- | ---------------------------------- |
+| `NodeWorkerEnvRunner`  | Worker thread                   | `workerData` / `parentPort`        |
+| `NodeProcessEnvRunner` | Child process (`fork`)          | `ENV_RUNNER_DATA` / `process.send` |
+| `BunProcessEnvRunner`  | Bun or Node.js process          | `Bun.spawn` IPC or `fork()`        |
+| `DenoProcessEnvRunner` | Deno process                    | `deno run` with IPC channel        |
+| `SelfEnvRunner`        | In-process                      | In-memory channel                  |
+| `MiniflareEnvRunner`   | Cloudflare Workers (miniflare)  | WebSocket pair via `dispatchFetch` |
+| `VercelEnvRunner`      | Worker thread (Vercel context)  | `workerData` / `parentPort`        |
+| `NetlifyEnvRunner`     | Worker thread (Netlify context) | `workerData` / `parentPort`        |
 
 #### Miniflare Runner
 
@@ -289,6 +293,32 @@ const runner2 = new MiniflareEnvRunner({
 // Fully destroy: runner.dispose() or MiniflareEnvRunner.disposeAll()
 ```
 
+#### Vercel Runner
+
+Simulates a Vercel deployment environment with automatic header injection (`x-vercel-deployment-url`, `x-vercel-forwarded-for`, forwarding headers) and global context.
+
+```ts
+import { VercelEnvRunner } from "env-runner/runners/vercel";
+
+const runner = new VercelEnvRunner({
+  name: "my-app",
+  data: { entry: "./app.ts" },
+});
+```
+
+#### Netlify Runner
+
+Simulates a Netlify deployment environment with automatic header injection (`x-nf-client-connection-ip`, `x-nf-account-id`, `x-nf-site-id`, `x-nf-deploy-id`, `x-nf-deploy-context`, `x-nf-geo`, `x-nf-request-id`, forwarding headers) and `globalThis.Netlify` setup:
+
+```ts
+import { NetlifyEnvRunner } from "env-runner/runners/netlify";
+
+const runner = new NetlifyEnvRunner({
+  name: "my-app",
+  data: { entry: "./app.ts" },
+});
+```
+
 ### Vite Environment API
 
 env-runner provides helpers for integrating with Vite's [Environment API](https://vite.dev/guide/api-environment-runtimes.html):

package.json

@@ -26,6 +26,8 @@
     "./runners/miniflare": "./dist/runners/miniflare/runner.mjs",
     "./runners/vercel": "./dist/runners/vercel/runner.mjs",
     "./runners/vercel/worker": "./dist/runners/vercel/worker.mjs",
+    "./runners/netlify": "./dist/runners/netlify/runner.mjs",
+    "./runners/netlify/worker": "./dist/runners/netlify/worker.mjs",
     "./vite": "./dist/vite.mjs"
   },
   "scripts": {
@@ -46,6 +48,7 @@
     "srvx": "^0.11.13"
   },
   "devDependencies": {
+    "@netlify/runtime": "^4.1.20",
     "@types/node": "^25.5.0",
     "@typescript/native-preview": "^7.0.0-dev.20260327.2",
     "@vitest/coverage-v8": "^4.1.2",
@@ -61,11 +64,15 @@
     "vitest": "^4.1.2"
   },
   "peerDependencies": {
+    "@netlify/runtime": "^4",
     "miniflare": "^4.20260317.3"
   },
   "peerDependenciesMeta": {
     "miniflare": {
       "optional": true
+    },
+    "@netlify/runtime": {
+      "optional": true
     }
   },
   "packageManager": "pnpm@10.33.0"