The best way to control Claude Code, Codex and more from any computer or phone

main
ts 482 lines 21 KB
Raw
1 import * as NodeNet from "node:net";
2 import * as NodePath from "node:path";
3 import type { BindingHooks, Module, RuntimeWorker } from "@alchemy.run/cloudflare-runtime/core";
4 import * as Assets from "@alchemy.run/cloudflare-runtime/core/bindings/assets/Assets";
5 import * as DurableObjectNamespace from "@alchemy.run/cloudflare-runtime/core/bindings/DurableObjectNamespace";
6 import * as Service from "@alchemy.run/cloudflare-runtime/core/bindings/Service";
7 import { DEFAULT_COMPATIBILITY_DATE } from "@alchemy.run/cloudflare-runtime/core/internal/constants";
8 import * as Runtime from "@alchemy.run/cloudflare-runtime/core/Runtime";
9 import * as RuntimeServices from "@alchemy.run/cloudflare-runtime/core/RuntimeServices";
10 import * as Credentials from "@distilled.cloud/cloudflare/Credentials";
11 import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
12 import * as NodeServices from "@effect/platform-node/NodeServices";
13 import type * as Context from "effect/Context";
14 import * as Effect from "effect/Effect";
15 import * as FileSystem from "effect/FileSystem";
16 import * as FetchHttpClient from "effect/http/FetchHttpClient";
17 import * as Layer from "effect/Layer";
18 import * as Path from "effect/Path";
19 import type * as Scope from "effect/Scope";
20 import * as FrameworkCore from "../core/index.ts";
21 import * as Bundle from "./Bundle.ts";
22 import * as DevServer from "./DevServer.ts";
23 import * as Runner from "./Runner.ts";
24
25 /**
26 * The subset of the e2e-harness `options.vite` convention this integration
27 * reads: the cloudflare worker configuration (compatibility date/flags,
28 * worker name/bindings/assets). Structurally compatible with
29 * `CloudflareVitePluginOptions` so harness fixtures stay uniform.
30 */
31 export interface NextjsWorkerConfig {
32 readonly compatibilityDate?: string | undefined;
33 readonly compatibilityFlags?: Array<string> | undefined;
34 readonly worker?:
35 | Omit<RuntimeWorker<BindingHooks>, "compatibilityDate" | "compatibilityFlags" | "modules">
36 | undefined;
37 }
38
39 /** Options for the Next.js (OpenNext-based) `Framework` integration. */
40 export interface NextjsFrameworkOptions {
41 /**
42 * Cloudflare worker configuration, following the e2e harness convention
43 * (`options.vite` carries compatibility date/flags and the worker's
44 * name/bindings/assets).
45 */
46 readonly vite?: NextjsWorkerConfig | undefined;
47 /** Next.js/OpenNext-specific knobs. */
48 readonly nextjs?:
49 | {
50 /**
51 * Optional explicit OpenNext config for direct framework consumers.
52 * Otherwise load `open-next.config.ts` when present, or generate defaults.
53 */
54 readonly configPath?: string | undefined;
55 /** Resource-selected cache adapters. Defaults to the read-only static-assets cache. */
56 readonly cache?: "static-assets" | "kv" | undefined;
57 /**
58 * The command the OpenNext pipeline runs to build the Next.js app.
59 * Takes precedence over an explicitly supplied OpenNext config.
60 * @default "npx next build"
61 */
62 readonly buildCommand?: string | undefined;
63 /** Skip the internal `next build` (reuse an existing `.next`). */
64 readonly skipNextBuild?: boolean | undefined;
65 /** Minify the OpenNext bundling steps and the final bundle pass. */
66 readonly minify?: boolean | undefined;
67 /**
68 * Enable OpenNext debug logging and verbose workerd output in dev
69 * (workerd otherwise swallows uncaught worker exceptions).
70 */
71 readonly debug?: boolean | undefined;
72 }
73 | undefined;
74 /** Dev-server behavior. */
75 readonly dev?:
76 | {
77 /**
78 * - `"preview"` (default): build the OpenNext worker and serve it
79 * under `cloudflare-runtime` (workerd) — production parity, no HMR.
80 * - `"hmr"`: run the real `next dev` (Turbopack HMR) in Node, with
81 * the worker's bindings proxied from `cloudflare-runtime` and
82 * planted on OpenNext's `getCloudflareContext()` contract
83 * ({@link DevServer.start}). App code runs in Node, not workerd —
84 * CF-specific runtime behavior and ISR/caching semantics still
85 * need `"preview"`.
86 * @default "preview"
87 */
88 readonly mode?: "preview" | "hmr" | undefined;
89 }
90 | undefined;
91 /** Project root. Defaults to the process working directory. */
92 readonly root?: string | undefined;
93 /**
94 * The host's runtime stack (a `Context.Context<RuntimeServices>`, e.g.
95 * alchemy's `DevContext.runtimeContext`). When provided, dev servers host
96 * the binding proxy in it instead of building the credential-free internal
97 * layer — this is what makes `Alchemy.remote()` bindings resolve in dev.
98 * Typed `unknown` to keep the option JSON-tolerant at the boundary; it is
99 * narrowed internally.
100 */
101 readonly services?: unknown;
102 }
103
104 /**
105 * Extract the edge-runtime function paths from `.next/server/
106 * middleware-manifest.json`. `middleware` entries are supported (OpenNext
107 * runs the middleware in the worker); `functions` entries are routes/pages
108 * compiled for the edge runtime, which `@opennextjs/cloudflare` does not
109 * support.
110 */
111 export const listEdgeFunctions = (manifest: unknown): Array<string> => {
112 if (typeof manifest !== "object" || manifest === null) return [];
113 const functions = (manifest as { functions?: Record<string, unknown> }).functions;
114 return functions === undefined ? [] : Object.keys(functions);
115 };
116
117 export { DEFAULT_COMPATIBILITY_DATE };
118
119 /** The server-module name of the worker entry (`serverModules[0]`). */
120 export const WORKER_ENTRY_MODULE = `worker/${Bundle.WORKER_ENTRY_NAME}`;
121
122 /** The OpenNext revalidation-queue Durable Object class. */
123 export const DO_QUEUE_CLASS = "DOQueueHandler";
124 /** The binding name OpenNext expects for the revalidation-queue DO. */
125 export const DO_QUEUE_BINDING = "NEXT_CACHE_DO_QUEUE";
126 /** The self service binding OpenNext uses for ISR revalidation fetches. */
127 export const SELF_REFERENCE_BINDING = "WORKER_SELF_REFERENCE";
128
129 /** Build the {@link Runner.RunnerConfig} for a project (exported for testing). */
130 export const makeRunnerConfig = (
131 root: string,
132 options?: NextjsFrameworkOptions,
133 ): Runner.RunnerConfig => ({
134 appDir: root,
135 configPath: options?.nextjs?.configPath,
136 cache: options?.nextjs?.cache ?? "static-assets",
137 compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
138 skipNextBuild: options?.nextjs?.skipNextBuild ?? false,
139 minify: options?.nextjs?.minify ?? false,
140 debug: options?.nextjs?.debug ?? false,
141 buildCommand: options?.nextjs?.buildCommand,
142 });
143
144 /**
145 * Map a `BuildOutput`'s server modules to cloudflare-runtime worker modules
146 * (exported for testing). Sourcemaps are dropped; binary content is passed
147 * through as bytes, text content as strings.
148 */
149 export const toRuntimeModules = (
150 serverModules: ReadonlyArray<FrameworkCore.OutputFile>,
151 ): Array<Module> =>
152 serverModules.flatMap((file): Module | Array<Module> => {
153 const asText = () =>
154 typeof file.content === "string" ? file.content : Buffer.from(file.content).toString("utf8");
155 const asBytes = () =>
156 typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content;
157 switch (NodePath.extname(file.name)) {
158 case ".js":
159 case ".mjs":
160 return { name: file.name, type: "ESModule", content: asText() };
161 case ".cjs":
162 return { name: file.name, type: "CommonJsModule", content: asText() };
163 case ".json":
164 return { name: file.name, type: "Json", content: asText() };
165 case ".wasm":
166 return { name: file.name, type: "Wasm", content: asBytes() };
167 case ".bin":
168 return { name: file.name, type: "Data", content: asBytes() };
169 case ".map":
170 return [];
171 default:
172 return { name: file.name, type: "Text", content: asText() };
173 }
174 });
175
176 /**
177 * Whether the entry module exports the OpenNext revalidation-queue Durable
178 * Object class (exported for testing). OpenNext's `worker.js` re-exports the
179 * DO classes it ships; when present, dev declares the same-script
180 * SQLite-backed namespace + binding so `doQueue`-configured apps work and
181 * `memoryQueue` apps keep parity with the deployed worker shape.
182 */
183 export const hasDoQueueClass = (entry: FrameworkCore.OutputFile | undefined): boolean => {
184 if (entry === undefined) return false;
185 const content =
186 typeof entry.content === "string" ? entry.content : Buffer.from(entry.content).toString("utf8");
187 return content.includes(DO_QUEUE_CLASS);
188 };
189
190 /** The services the runtime layer for dev is built from. */
191 const makeRuntimeLayer = () =>
192 RuntimeServices.layerRuntime({
193 api: {
194 // Local-only serving: the account id is only consulted when remote
195 // bindings are used, which a preview-parity dev server does not
196 // require. Fall back to a placeholder so credentials stay optional.
197 accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "distilled-nextjs-local",
198 },
199 }).pipe(
200 Layer.provideMerge(NodeServices.layer),
201 Layer.provide(Layer.merge(Credentials.fromEnv(), FetchHttpClient.layer)),
202 );
203
204 /**
205 * Front a target server with a TCP proxy on a fixed local port.
206 * `Runtime.start` always binds an ephemeral port, so honoring
207 * `FrameworkDevOptions.port` requires the forwarder.
208 */
209 const proxyToPort = (
210 port: number,
211 target: URL,
212 ): Effect.Effect<URL, FrameworkCore.FrameworkError, Scope.Scope> =>
213 Effect.acquireRelease(
214 Effect.callback<NodeNet.Server, FrameworkCore.FrameworkError>((resume) => {
215 const server = NodeNet.createServer((socket) => {
216 const upstream = NodeNet.connect(Number(target.port), target.hostname);
217 socket.pipe(upstream);
218 upstream.pipe(socket);
219 const teardown = () => {
220 socket.destroy();
221 upstream.destroy();
222 };
223 socket.on("error", teardown);
224 upstream.on("error", teardown);
225 socket.on("close", teardown);
226 upstream.on("close", teardown);
227 });
228 server.once("error", (cause) =>
229 resume(
230 Effect.fail(
231 new FrameworkCore.FrameworkError({
232 framework: "nextjs",
233 message: `Failed to listen on port ${port}`,
234 cause,
235 }),
236 ),
237 ),
238 );
239 server.listen(port, "127.0.0.1", () => resume(Effect.succeed(server)));
240 }),
241 (server) =>
242 Effect.callback<void>((resume) => {
243 server.close(() => resume(Effect.void));
244 }),
245 ).pipe(Effect.map(() => new URL(`http://127.0.0.1:${port}`)));
246
247 /**
248 * The Next.js implementation of framework-core's `Framework` service,
249 * built on the `@opennextjs/cloudflare` build pipeline — wrangler-free:
250 *
251 * - `build` runs the pipeline in a disposable child process (`runner.mjs`
252 * vendors the two thin config wrappers so no wrangler code is ever
253 * imported), then performs the final bundle pass wrangler would normally
254 * do at deploy time ({@link Bundle.bundleWorker}), populates the
255 * static-assets incremental cache, and returns the `BuildOutput` in-memory.
256 * - `dev` (default mode `"preview"`) serves the built worker under
257 * `@alchemy.run/cloudflare-runtime/core` (workerd) with the OpenNext worker
258 * shape: `ASSETS` + run-worker-first, a `WORKER_SELF_REFERENCE` self
259 * service binding, and the same-script SQLite-backed revalidation-queue
260 * Durable Object. No HMR — file watching/rebuild is a later phase.
261 * - `dev` with `options.dev.mode: "hmr"` runs the real `next dev` (Turbopack
262 * HMR) in Node with the worker's bindings proxied from
263 * `cloudflare-runtime` ({@link DevServer.start}) — see the mode's fidelity
264 * notes on {@link NextjsFrameworkOptions}.
265 */
266 export const make = (
267 options?: NextjsFrameworkOptions,
268 ): Layer.Layer<FrameworkCore.Framework, never, FileSystem.FileSystem | Path.Path> =>
269 Layer.effect(
270 FrameworkCore.Framework,
271 Effect.gen(function* () {
272 const fs = yield* FileSystem.FileSystem;
273 const path = yield* Path.Path;
274
275 const fail = (message: string) => (cause: unknown) =>
276 new FrameworkCore.FrameworkError({
277 framework: "nextjs",
278 message,
279 cause,
280 });
281
282 const spawnerLayer = NodeChildProcessSpawner.layer.pipe(
283 Layer.provide(
284 Layer.merge(Layer.succeed(FileSystem.FileSystem)(fs), Layer.succeed(Path.Path)(path)),
285 ),
286 );
287
288 const resolveRoot = (override: string | undefined) =>
289 Effect.sync(() => path.resolve(override ?? options?.root ?? process.cwd()));
290
291 const paths = (root: string, openNextDirectory: string) => ({
292 openNextDirectory,
293 clientDirectory: path.join(openNextDirectory, "assets"),
294 cacheDirectory: path.join(openNextDirectory, "cache"),
295 distDirectory: path.resolve(root, "dist"),
296 workerDirectory: path.resolve(root, "dist", "worker"),
297 });
298
299 const build = Effect.fn(function* (buildOptions?: FrameworkCore.FrameworkBuildOptions) {
300 const root = yield* resolveRoot(buildOptions?.root);
301 // 1. The OpenNext build pipeline (spawns `next build` internally).
302 const buildPaths = yield* Runner.runOpenNextBuild(makeRunnerConfig(root, options)).pipe(
303 Effect.mapError((error) => fail(error.message)(error.cause)),
304 Effect.provide(spawnerLayer),
305 Effect.provideService(FileSystem.FileSystem, fs),
306 Effect.provideService(Path.Path, path),
307 );
308 const p = paths(root, buildPaths.openNextDirectory);
309
310 // 1.5. Edge-runtime routes/pages are not supported by
311 // @opennextjs/cloudflare (it shims `next/dist/compiled/edge-runtime`
312 // to an empty module, so they 500 at runtime). Fail the build with
313 // the exact route list instead of shipping a mystery 500 — the same
314 // code runs fine on Workers under the node runtime.
315 const manifestPath = path.join(
316 buildPaths.appBuildOutputPath,
317 ".next",
318 "server",
319 "middleware-manifest.json",
320 );
321 const manifestRaw = yield* fs
322 .readFileString(manifestPath)
323 .pipe(Effect.orElseSucceed(() => undefined));
324 if (manifestRaw !== undefined) {
325 const edgeRoutes = yield* Effect.try({
326 try: () => listEdgeFunctions(JSON.parse(manifestRaw)),
327 catch: fail(`Failed to parse ${manifestPath}`),
328 });
329 if (edgeRoutes.length > 0) {
330 return yield* fail(
331 `Edge-runtime routes/pages are not supported by @opennextjs/cloudflare: ${edgeRoutes.join(", ")}. ` +
332 `Remove \`export const runtime = "edge"\` from these modules — the node runtime runs on Workers.`,
333 )(undefined);
334 }
335 }
336
337 // 2. The final bundle pass (what wrangler does implicitly on deploy).
338 yield* fs.remove(p.workerDirectory, { recursive: true }).pipe(Effect.ignore);
339 yield* Bundle.bundleWorker({
340 openNextDirectory: p.openNextDirectory,
341 outDirectory: p.workerDirectory,
342 minify: options?.nextjs?.minify ?? false,
343 }).pipe(Effect.mapError((error) => fail(error.message)(error.cause)));
344
345 // 3. populateCache, static-assets flavor: prerendered ISR/fetch cache
346 // entries are served read-only through the ASSETS binding.
347 const hasCache = yield* fs.exists(p.cacheDirectory).pipe(Effect.orElseSucceed(() => false));
348 if (hasCache) {
349 yield* fs
350 .copy(p.cacheDirectory, path.join(p.clientDirectory, "cdn-cgi", "_next_cache"), {
351 overwrite: true,
352 })
353 .pipe(Effect.mapError(fail("Failed to populate the static-assets incremental cache")));
354 }
355
356 // 4. Collect the BuildOutput contract from disk (entry first).
357 const files = yield* FrameworkCore.readServerModulesFromDisk({
358 directory: p.workerDirectory,
359 prefix: "worker",
360 }).pipe(
361 Effect.provideService(FileSystem.FileSystem, fs),
362 Effect.mapError((error) => fail(error.message)(error.cause)),
363 );
364 const output: FrameworkCore.BuildOutput = {
365 distDirectory: p.distDirectory,
366 clientDirectory: p.clientDirectory,
367 serverModules: FrameworkCore.sortServerModules(files, WORKER_ENTRY_MODULE),
368 externalWorkspaces: new Set(),
369 };
370 return output;
371 });
372
373 // The runtime context the dev servers host their binding proxy in:
374 // the caller-provided host stack (includes remote-bindings support,
375 // so `Alchemy.remote()` bindings resolve) when present, the internal
376 // credential-free layer otherwise.
377 const resolveRuntimeContext = Effect.fn(function* () {
378 if (options?.services !== undefined) {
379 return options.services as Context.Context<RuntimeServices.RuntimeServices>;
380 }
381 const scope = yield* Effect.scope;
382 return yield* Layer.buildWithScope(makeRuntimeLayer(), scope).pipe(
383 Effect.mapError(fail("Failed to start the cloudflare-runtime services")),
384 );
385 });
386
387 const dev = Effect.fn(function* (devOptions?: FrameworkCore.FrameworkDevOptions) {
388 const root = yield* resolveRoot(devOptions?.root);
389
390 // Dev v2 ("hmr"): real `next dev` (Turbopack HMR) in Node, bindings
391 // proxied from cloudflare-runtime onto OpenNext's
392 // getCloudflareContext() contract. No OpenNext build involved.
393 if (options?.dev?.mode === "hmr") {
394 const worker = options?.vite?.worker;
395 const context = yield* resolveRuntimeContext();
396 const server = yield* DevServer.start({
397 root,
398 port: devOptions?.port,
399 bindings: worker?.bindings ?? [],
400 compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
401 compatibilityFlags: [
402 ...new Set(["nodejs_compat", ...(options?.vite?.compatibilityFlags ?? [])]),
403 ],
404 ...(worker?.name !== undefined ? { proxyName: `${worker.name}-dev-proxy` } : {}),
405 ...(worker?.workerd !== undefined ? { workerd: worker.workerd } : {}),
406 logging: options?.nextjs?.debug ? { verbose: true } : worker?.logging,
407 }).pipe(Effect.provideContext(context));
408 return { url: server.url.href };
409 }
410
411 // Preview parity: always build on dev start (OpenNext memoizes where
412 // it can). Watch + rebuild is a later phase.
413 const output = yield* build({ root });
414 if (output.serverModules === undefined || output.serverModules.length === 0) {
415 return yield* fail("The build produced no server modules")(undefined);
416 }
417 const modules = toRuntimeModules(output.serverModules);
418 const worker = options?.vite?.worker;
419
420 const declaresDoQueue = (worker?.durableObjectNamespaces ?? []).some(
421 (namespace) => namespace.className === DO_QUEUE_CLASS,
422 );
423 const withDoQueue = !declaresDoQueue && hasDoQueueClass(output.serverModules[0]);
424
425 const context = yield* resolveRuntimeContext();
426
427 const url = yield* Runtime.Runtime.use((runtime) =>
428 runtime.start({
429 name: worker?.name ?? "distilled-nextjs-dev",
430 compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
431 compatibilityFlags: [
432 ...new Set(["nodejs_compat", ...(options?.vite?.compatibilityFlags ?? [])]),
433 ],
434 modules,
435 bindings: [
436 Assets.local("ASSETS"),
437 Service.self(SELF_REFERENCE_BINDING),
438 ...(withDoQueue
439 ? [
440 DurableObjectNamespace.local({
441 binding: DO_QUEUE_BINDING,
442 className: DO_QUEUE_CLASS,
443 }),
444 ]
445 : []),
446 ...(worker?.bindings ?? []),
447 ],
448 assets: {
449 ...worker?.assets,
450 directory: output.clientDirectory,
451 runWorkerFirst: worker?.assets?.runWorkerFirst ?? true,
452 },
453 durableObjectNamespaces: [
454 ...(withDoQueue ? [{ className: DO_QUEUE_CLASS, sql: true }] : []),
455 ...(worker?.durableObjectNamespaces ?? []),
456 ],
457 ...(worker?.hyperdrives !== undefined ? { hyperdrives: worker.hyperdrives } : {}),
458 ...(worker?.queueConsumers !== undefined
459 ? { queueConsumers: worker.queueConsumers }
460 : {}),
461 ...(worker?.unsafe !== undefined ? { unsafe: worker.unsafe } : {}),
462 ...(worker?.workerd !== undefined ? { workerd: worker.workerd } : {}),
463 logging: options?.nextjs?.debug ? { verbose: true } : worker?.logging,
464 }),
465 ).pipe(
466 Effect.provideContext(context),
467 Effect.mapError(fail("Failed to start the dev worker in cloudflare-runtime")),
468 );
469
470 if (devOptions?.port !== undefined && String(devOptions.port) !== url.port) {
471 const proxied = yield* proxyToPort(devOptions.port, url);
472 return { url: proxied.href };
473 }
474 return { url: url.href };
475 });
476
477 return FrameworkCore.Framework.of({
478 build: (buildOptions) => build(buildOptions),
479 dev: (devOptions) => dev(devOptions),
480 });
481 }),
482 );