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

main
ts 608 lines 22.7 KB
Raw
1 import * as NodeCrypto from "node:crypto";
2 import * as NodePath from "node:path";
3 import { fileURLToPath } from "node:url";
4 /**
5 * `@alchemy.run/frontend-frameworks/octane/source` — alchemy Worker source provider for
6 * OctaneJS projects.
7 *
8 * The default export satisfies alchemy's `WorkerSourceModule` contract
9 * (`packages/cloudflare/src/Workers/Source.ts`) **structurally**:
10 * the `Source*` shapes below mirror alchemy's `SourceProvider` /
11 * `SourceContext` / `SourceBuildOutput` interfaces rather than importing
12 * them, so this package carries no dependency on alchemy. Version skew
13 * degrades to a load-time `SourceProviderError` on the alchemy side.
14 *
15 * Semantics mirror alchemy's built-in vite source
16 * (`Workers/Sources/Vite.ts`):
17 *
18 * - `build()` runs the Octane Framework service (the project's own
19 * Vite plugins compile the client and server; Alchemy generates the
20 * `dist/server/worker.js` entry without requiring a hosting adapter) and
21 * maps its `BuildOutput` onto the source contract: `serverModules`
22 * (entry first) → bundle files, `clientDirectory` (`dist/client`) →
23 * assets (manifest-hashed, honoring `.assetsignore` / `_headers` /
24 * `_redirects`), project-tree hash → the `input` hash slot.
25 * - `hash()` recomputes the `input` hash **without building** — a memo hash
26 * over the project tree (gitignore-aware by default, narrowable via
27 * `memo.include`/`memo.exclude`), the lockfile, this package's version,
28 * and the build-affecting options.
29 * - `dev()` starts Octane's own Vite dev server (the plugin's dev SSR
30 * middleware — rendering, server routes, and RPC run in-process with full
31 * HMR) and returns the server-mode dev handle. NOTE: Octane's dev
32 * middleware supplies no request-scoped platform bindings
33 * (`context.platform` is `undefined` in dev — an upstream limitation), so
34 * Worker bindings are not observable from dev-mode app code yet.
35 */
36 import * as Data from "effect/Data";
37 import * as Effect from "effect/Effect";
38 import * as FileSystem from "effect/FileSystem";
39 import type * as Path from "effect/Path";
40 import type { PlatformError } from "effect/PlatformError";
41 import type * as Scope from "effect/Scope";
42 import { glob } from "tinyglobby";
43 import { resolveBuildEnv, runBuildChild } from "../core/BuildChild.ts";
44 import { makeCloudflareTarget } from "./cloudflare.ts";
45 import { make as makeOctane, type OctaneOptions } from "./Octane.ts";
46
47 const PROVIDER = "@alchemy.run/frontend-frameworks/octane/source";
48
49 // ─────────────────────────────────────────────────────────────────────
50 // Structural mirror of alchemy's Worker source contract
51 // (packages/cloudflare/src/Workers/Source.ts). Do not import
52 // alchemy here — the contract is structural by design.
53 // ─────────────────────────────────────────────────────────────────────
54
55 /** Mirror of alchemy's `SourceHash`. */
56 export interface SourceHash {
57 readonly bundle: string | undefined;
58 readonly assets: string | undefined;
59 readonly input: string | undefined;
60 readonly additionalWorkspaces: Array<string> | undefined;
61 }
62
63 /** Mirror of alchemy's `Bundle.BundleFile` / `Bundle.BundleOutput`. */
64 export interface SourceBundleFile {
65 readonly path: string;
66 readonly content: string | Uint8Array;
67 readonly hash: string;
68 }
69
70 export interface SourceBundleOutput {
71 readonly files: [SourceBundleFile, ...Array<SourceBundleFile>];
72 readonly hash: string;
73 }
74
75 /** Mirror of alchemy's `AssetReadResult` (`Workers/Assets.ts`). */
76 export interface SourceAssetReadResult {
77 directory: string;
78 config: Record<string, unknown> | undefined;
79 manifest: Record<string, { hash: string; size: number }>;
80 _headers: string | undefined;
81 _redirects: string | undefined;
82 hash: string;
83 }
84
85 /** Mirror of alchemy's `SourceBuildOutput`. */
86 export interface SourceBuildOutput {
87 readonly bundle: SourceBundleOutput | undefined;
88 readonly assets: SourceAssetReadResult | undefined;
89 readonly hash: SourceHash;
90 }
91
92 /** Mirror of alchemy's `SourceContext` (the subset this source reads). */
93 export interface SourceContext {
94 readonly id: string;
95 readonly workerName: string;
96 readonly compatibility: {
97 readonly date: string;
98 readonly flags: Array<string>;
99 };
100 readonly stack: { readonly name: string; readonly stage: string };
101 readonly env: Record<string, unknown> | undefined;
102 readonly assets: Record<string, unknown> | string | undefined;
103 }
104
105 /** Mirror of alchemy's `DevContext` (the subset this source reads). */
106 export interface SourceDevContext extends SourceContext {
107 /**
108 * Runtime wiring derived by alchemy's LocalWorkerProvider. Octane's dev
109 * server cannot serve platform bindings yet (see the module doc), so the
110 * worker wiring is currently unused — carried for contract parity.
111 */
112 readonly worker: {
113 readonly name: string;
114 readonly bindings: ReadonlyArray<unknown>;
115 };
116 /** The host's pre-built `Context<RuntimeServices>` (opaque here; unused). */
117 readonly runtimeContext: unknown;
118 }
119
120 /** Mirror of alchemy's server-mode `SourceDevHandle`. */
121 export interface SourceDevHandle {
122 readonly mode: "server";
123 readonly url: URL;
124 readonly serviceBinding?: "http";
125 }
126
127 /**
128 * Same tag as alchemy's `Cloudflare.Workers.SourceProviderError`, so the
129 * errors this module raises are members of alchemy's closed `SourceError`
130 * union structurally.
131 */
132 export class SourceProviderError extends Data.TaggedError(
133 "Cloudflare.Workers.SourceProviderError",
134 )<{
135 readonly provider: string;
136 readonly message: string;
137 readonly cause?: unknown;
138 }> {}
139
140 export type SourceError = SourceProviderError | PlatformError;
141
142 type SourceServices = FileSystem.FileSystem | Path.Path;
143
144 /** Mirror of alchemy's `SourceProvider` (structural). */
145 export interface SourceProvider {
146 readonly ownsAssets: boolean;
147 readonly build: (
148 ctx: SourceContext,
149 ) => Effect.Effect<SourceBuildOutput, SourceError, SourceServices>;
150 readonly hash: (
151 ctx: SourceContext,
152 previous: SourceHash | undefined,
153 ) => Effect.Effect<Partial<SourceHash>, SourceError, SourceServices>;
154 readonly dev: (
155 ctx: SourceDevContext,
156 ) => Effect.Effect<SourceDevHandle, SourceError, SourceServices | Scope.Scope>;
157 }
158
159 // ─────────────────────────────────────────────────────────────────────
160 // Descriptor options (JSON-serializable — they persist in alchemy state
161 // and participate in the Worker's metadata hash)
162 // ─────────────────────────────────────────────────────────────────────
163
164 export interface OctaneMemoOptions {
165 /** Glob patterns of files to hash, relative to `rootDir`. @default all non-gitignored files */
166 readonly include?: Array<string> | undefined;
167 /** Glob patterns to exclude. @default gitignore rules from `rootDir` up to the repo root */
168 readonly exclude?: Array<string> | undefined;
169 /**
170 * Include the nearest package-manager lockfile in the hash.
171 * @default true when both `include` and `exclude` are unset
172 */
173 readonly lockfile?: boolean | undefined;
174 }
175
176 export interface OctaneSourceOptions {
177 /**
178 * Octane project root (the directory containing `vite.config.ts` and
179 * `octane.config.ts`). Relative paths resolve from the process working
180 * directory. @default process.cwd()
181 */
182 readonly rootDir?: string | undefined;
183 /** Narrows the rebuild-detection input hash. */
184 readonly memo?: OctaneMemoOptions | undefined;
185 }
186
187 // ─────────────────────────────────────────────────────────────────────
188 // Hashing (mirrors alchemy's Command/Memo.ts + Util/sha256.ts semantics:
189 // machine-independent — only relative paths and file bytes are hashed)
190 // ─────────────────────────────────────────────────────────────────────
191
192 const sha256Hex = (input: string | Uint8Array): Effect.Effect<string> =>
193 Effect.sync(() => NodeCrypto.createHash("sha256").update(input).digest("hex"));
194
195 /** Recursively sort object keys so JSON.stringify is order-stable. */
196 const stableValue = (value: unknown): unknown => {
197 if (Array.isArray(value)) {
198 return value.map(stableValue);
199 }
200 if (value !== null && typeof value === "object") {
201 return Object.fromEntries(
202 Object.entries(value as Record<string, unknown>)
203 .filter(([, v]) => v !== undefined)
204 .sort(([a], [b]) => a.localeCompare(b))
205 .map(([k, v]) => [k, stableValue(v)]),
206 );
207 }
208 return value;
209 };
210
211 const sha256Stable = (input: unknown): Effect.Effect<string> =>
212 sha256Hex(JSON.stringify(stableValue(input) ?? null));
213
214 /**
215 * Convert gitignore-style rules into glob `ignore` patterns — a copy of
216 * alchemy's `Util/gitignore-rules-to-globs.ts` (common cases only).
217 */
218 const gitignoreRulesToGlobs = (rules: ReadonlyArray<string>): Array<string> => {
219 const out: Array<string> = [];
220 for (const raw of rules) {
221 const line = raw.trim();
222 if (line.length === 0 || line.startsWith("#") || line.startsWith("!")) {
223 continue;
224 }
225 let rest = line;
226 const dirOnly = rest.endsWith("/");
227 if (dirOnly) {
228 rest = rest.slice(0, -1);
229 }
230 rest = rest.replace(/\\/g, "/");
231 if (rest.length === 0) continue;
232 const anchored = rest.startsWith("/");
233 if (anchored) {
234 rest = rest.slice(1);
235 }
236 if (rest.length === 0) continue;
237 const hasSlash = rest.includes("/");
238 if (dirOnly) {
239 out.push(anchored || hasSlash ? `${rest}/**` : `**/${rest}/**`);
240 } else if (anchored || hasSlash) {
241 out.push(rest, `${rest}/**`);
242 } else {
243 out.push(`**/${rest}`, `**/${rest}/**`);
244 }
245 }
246 return out;
247 };
248
249 const findUp = Effect.fnUntraced(function* (
250 fs: FileSystem.FileSystem,
251 cwd: string,
252 filenames: Array<string>,
253 ) {
254 let dir = cwd;
255 for (;;) {
256 for (const filename of filenames) {
257 const file = NodePath.join(dir, filename);
258 if (yield* fs.exists(file)) {
259 return file;
260 }
261 }
262 const parent = NodePath.dirname(dir);
263 if (parent === dir) {
264 return undefined;
265 }
266 dir = parent;
267 }
268 });
269
270 /** Collect `.gitignore` rules from `cwd` up to the repo root (parents first). */
271 const readGitIgnoreRules = (
272 fs: FileSystem.FileSystem,
273 cwd: string,
274 ): Effect.Effect<Array<string>, PlatformError> =>
275 Effect.gen(function* () {
276 const rules = yield* fs.readFileString(NodePath.join(cwd, ".gitignore")).pipe(
277 Effect.map((file) => file.split("\n")),
278 Effect.catchTag("PlatformError", () => Effect.succeed([] as Array<string>)),
279 );
280 const parent = NodePath.dirname(cwd);
281 if (parent === cwd || (yield* fs.exists(NodePath.join(cwd, ".git")))) {
282 return rules;
283 }
284 const parentRules = yield* readGitIgnoreRules(fs, parent);
285 return [...parentRules, ...rules];
286 });
287
288 /**
289 * Deterministic content hash of the files in `cwd` matched by `memo` —
290 * mirror of alchemy's `hashDirectory` (`Command/Memo.ts`).
291 */
292 const hashDirectory = Effect.fnUntraced(function* (
293 cwd: string,
294 memo: OctaneMemoOptions | undefined,
295 ) {
296 const fs = yield* FileSystem.FileSystem;
297 const include = memo?.include ?? ["**/*"];
298 const exclude = memo?.exclude ?? [
299 "**/.git/**",
300 ...gitignoreRulesToGlobs(yield* readGitIgnoreRules(fs, cwd)),
301 ];
302 const lockfile = memo?.lockfile ?? !(memo?.include || memo?.exclude);
303 const [files, lockfilePath] = yield* Effect.all(
304 [
305 Effect.promise(() =>
306 glob(include, {
307 cwd,
308 ignore: exclude,
309 onlyFiles: true,
310 expandDirectories: false,
311 dot: true,
312 }),
313 ),
314 lockfile
315 ? Effect.map(
316 findUp(fs, cwd, [
317 "bun.lock",
318 "bun.lockb",
319 "package-lock.json",
320 "pnpm-lock.yaml",
321 "yarn.lock",
322 ]),
323 (file) => (file ? NodePath.relative(cwd, file) : undefined),
324 )
325 : Effect.undefined,
326 ],
327 { concurrency: "unbounded" },
328 );
329 if (lockfilePath && !files.includes(lockfilePath)) {
330 files.push(lockfilePath);
331 }
332 const hashes = yield* Effect.forEach(
333 files.sort(),
334 (file) =>
335 fs.readFile(NodePath.join(cwd, file)).pipe(
336 Effect.flatMap(sha256Hex),
337 Effect.map((hash) => `${file}:${hash}`),
338 ),
339 { concurrency: 16 },
340 );
341 return yield* sha256Stable(hashes);
342 });
343
344 /** This package's version — part of the `input` hash so an integration upgrade busts the memo. */
345 const packageVersion = Effect.gen(function* () {
346 const fs = yield* FileSystem.FileSystem;
347 const dir = NodePath.dirname(fileURLToPath(import.meta.url));
348 const content = yield* fs.readFileString(NodePath.join(dir, "../../package.json"));
349 return (JSON.parse(content) as { version: string }).version;
350 });
351
352 /**
353 * The rebuild-free `input` hash: project tree + external workspaces +
354 * package version + build-affecting options. Mirrors alchemy's
355 * `hashViteInput` semantics (`Workers/Sources/Vite.ts`) — never hashes
356 * absolute paths, so relocating an identical tree is a no-op.
357 */
358 const hashOctaneInput = Effect.fnUntraced(function* (
359 rootDir: string,
360 options: OctaneSourceOptions,
361 workspaces: Iterable<string>,
362 ) {
363 const version = yield* packageVersion;
364 const hashWorkspace = (cwd: string, memo?: OctaneMemoOptions) =>
365 hashDirectory(NodePath.resolve(rootDir, cwd), memo).pipe(
366 Effect.map((hash) => `${NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd))}:${hash}`),
367 );
368 const [root, ...workspaceHashes] = yield* Effect.all(
369 [hashWorkspace(rootDir, options.memo), ...Array.from(workspaces, (cwd) => hashWorkspace(cwd))],
370 { concurrency: "unbounded" },
371 );
372 const hash = yield* sha256Stable({
373 version,
374 options: {
375 memo: options.memo,
376 },
377 tree: [root, ...workspaceHashes.sort()],
378 });
379 return {
380 hash,
381 workspaces: Array.from(workspaces, (cwd) =>
382 NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd)),
383 ),
384 };
385 });
386
387 // ─────────────────────────────────────────────────────────────────────
388 // Assets (mirror of alchemy's `readAssets` in `Workers/Assets.ts`:
389 // manifest of 32-hex content hashes, honoring `.assetsignore`,
390 // `_headers`, `_redirects`; the overall hash excludes the directory
391 // path so identical bytes hash identically across machines)
392 // ─────────────────────────────────────────────────────────────────────
393
394 const MAX_ASSET_SIZE = 1024 * 1024 * 25; // 25MB (Cloudflare limit)
395 const MAX_ASSET_COUNT = 20_000;
396
397 const maybeReadString = (fs: FileSystem.FileSystem, file: string) =>
398 fs
399 .readFileString(file)
400 .pipe(
401 Effect.catchTag("PlatformError", (error) =>
402 error.reason._tag === "NotFound" ? Effect.undefined : Effect.fail(error),
403 ),
404 );
405
406 const readAssetsDirectory = Effect.fnUntraced(function* (
407 directory: string,
408 config: Record<string, unknown> | undefined,
409 ) {
410 const fs = yield* FileSystem.FileSystem;
411 const [ignore, _headers, _redirects] = yield* Effect.all([
412 maybeReadString(fs, NodePath.join(directory, ".assetsignore")),
413 maybeReadString(fs, NodePath.join(directory, "_headers")),
414 maybeReadString(fs, NodePath.join(directory, "_redirects")),
415 ]);
416 const files = yield* Effect.promise(() =>
417 glob(["**/*"], {
418 cwd: directory,
419 ignore: [
420 ".assetsignore",
421 "_headers",
422 "_redirects",
423 ...gitignoreRulesToGlobs(ignore?.split("\n") ?? []),
424 ],
425 onlyFiles: true,
426 expandDirectories: false,
427 dot: true,
428 }),
429 );
430 if (files.length > MAX_ASSET_COUNT) {
431 return yield* new SourceProviderError({
432 provider: PROVIDER,
433 message: `Too many assets in ${directory} (maximum is ${MAX_ASSET_COUNT}, found ${files.length})`,
434 });
435 }
436 const entries = yield* Effect.forEach(
437 files.sort(),
438 Effect.fnUntraced(function* (name) {
439 const file = NodePath.join(directory, name);
440 const content = yield* fs.readFile(file);
441 if (content.byteLength > MAX_ASSET_SIZE) {
442 return yield* new SourceProviderError({
443 provider: PROVIDER,
444 message: `Asset ${name} is too large (the maximum size is 25 MB)`,
445 });
446 }
447 const hash = (yield* sha256Hex(content)).slice(0, 32);
448 return [`/${name.replaceAll("\\", "/")}`, { hash, size: content.byteLength }] as const;
449 }),
450 { concurrency: 16 },
451 );
452 const manifest = Object.fromEntries([...entries].sort((a, b) => a[0].localeCompare(b[0])));
453 const hash = yield* sha256Stable({ config, manifest, _headers, _redirects });
454 return {
455 directory,
456 config,
457 manifest,
458 _headers,
459 _redirects,
460 hash,
461 } satisfies SourceAssetReadResult;
462 });
463
464 // ─────────────────────────────────────────────────────────────────────
465 // The provider
466 // ─────────────────────────────────────────────────────────────────────
467
468 const wrapFrameworkError = (error: { readonly message: string; readonly cause?: unknown }) =>
469 new SourceProviderError({
470 provider: PROVIDER,
471 message: error.message,
472 cause: error.cause ?? error,
473 });
474
475 const assetsConfig = (assets: SourceContext["assets"]): Record<string, unknown> | undefined => {
476 if (assets === undefined || typeof assets === "string") {
477 return undefined;
478 }
479 const { directory: _directory, hash: _hash, ...config } = assets;
480 return Object.keys(config).length > 0 ? config : undefined;
481 };
482
483 /**
484 * The production build runs in a disposable child process with
485 * `cwd = project root` (see `core/BuildChild.ts`): the natively-loaded
486 * `vite.config.*` executes user plugins that may read the cwd, mutate
487 * `process.env`, or `process.chdir` — none of which may touch the engine
488 * process. The shared `core/BuildChildRunner`
489 * entry imports this module in the child and calls the exported
490 * {@link buildInChild}.
491 */
492 export interface OctaneBuildChildConfig {
493 readonly rootDir: string;
494 readonly compatibilityDate: string;
495 readonly compatibilityFlags: Array<string>;
496 }
497
498 export const buildInChild = (config: OctaneBuildChildConfig) =>
499 Effect.gen(function* () {
500 const framework = yield* makeOctane({
501 root: config.rootDir,
502 target: makeCloudflareTarget,
503 compatibilityDate: config.compatibilityDate,
504 compatibilityFlags: config.compatibilityFlags,
505 });
506 return yield* framework.build({ root: config.rootDir });
507 });
508
509 export const makeOctaneSource = (options: OctaneSourceOptions): SourceProvider => {
510 const rootDir = NodePath.resolve(options.rootDir ?? process.cwd());
511 const frameworkOptions = (ctx: SourceContext): OctaneOptions => ({
512 root: rootDir,
513 // This module is Cloudflare-specific by contract (it implements alchemy's
514 // Cloudflare Worker source), so it passes the target factory directly
515 // instead of relying on specifier resolution from the project's
516 // node_modules.
517 target: makeCloudflareTarget,
518 compatibilityDate: ctx.compatibility.date,
519 compatibilityFlags: ctx.compatibility.flags,
520 });
521 return {
522 ownsAssets: true,
523 build: Effect.fnUntraced(function* (ctx) {
524 const output = yield* runBuildChild({
525 module: import.meta.url,
526 rootDir,
527 framework: "octane",
528 env: resolveBuildEnv(ctx.env),
529 config: {
530 rootDir,
531 compatibilityDate: ctx.compatibility.date,
532 compatibilityFlags: ctx.compatibility.flags,
533 } satisfies OctaneBuildChildConfig,
534 }).pipe(Effect.mapError(wrapFrameworkError));
535 if (output.serverModules === undefined || output.serverModules.length === 0) {
536 return yield* new SourceProviderError({
537 provider: PROVIDER,
538 message: "The Octane build produced no server modules",
539 });
540 }
541 if (output.clientDirectory === undefined) {
542 return yield* new SourceProviderError({
543 provider: PROVIDER,
544 message: "The Octane build produced no client directory",
545 });
546 }
547 const files = output.serverModules.map((module): SourceBundleFile => ({
548 path: module.name,
549 content: module.content,
550 hash: module.hash,
551 })) as [SourceBundleFile, ...Array<SourceBundleFile>];
552 const [bundleHash, assets, input] = yield* Effect.all(
553 [
554 sha256Stable(files.map((file) => `${file.path}:${file.hash}`)),
555 readAssetsDirectory(
556 NodePath.resolve(rootDir, output.clientDirectory),
557 assetsConfig(ctx.assets),
558 ),
559 hashOctaneInput(rootDir, options, output.externalWorkspaces),
560 ],
561 { concurrency: "unbounded" },
562 );
563 return {
564 bundle: { files, hash: bundleHash },
565 assets,
566 hash: {
567 bundle: bundleHash,
568 assets: assets.hash,
569 input: input.hash,
570 additionalWorkspaces: input.workspaces,
571 },
572 } satisfies SourceBuildOutput;
573 }),
574 hash: Effect.fnUntraced(function* (_ctx, previous) {
575 const { hash, workspaces } = yield* hashOctaneInput(
576 rootDir,
577 options,
578 previous?.additionalWorkspaces ?? [],
579 );
580 return { input: hash, additionalWorkspaces: workspaces };
581 }),
582 dev: Effect.fnUntraced(function* (ctx: SourceDevContext) {
583 // Octane's dev server serves SSR/HMR in-process but supplies no
584 // request-scoped platform (see the module doc) — the worker's binding
585 // hooks (`ctx.worker.bindings`) cannot be served into dev app code yet.
586 const framework = yield* makeOctane(frameworkOptions(ctx));
587 const server = yield* framework
588 .dev({ root: rootDir, port: 0 })
589 .pipe(Effect.mapError(wrapFrameworkError));
590 return {
591 mode: "server",
592 url: new URL(server.url),
593 serviceBinding: "http",
594 } satisfies SourceDevHandle;
595 }),
596 };
597 };
598
599 /**
600 * The `WorkerSourceModule` contract: alchemy dynamically imports this module
601 * and calls `make(descriptor.options)`.
602 */
603 const sourceModule = {
604 make: (options: unknown): Effect.Effect<SourceProvider, SourceProviderError> =>
605 Effect.succeed(makeOctaneSource((options ?? {}) as OctaneSourceOptions)),
606 };
607
608 export default sourceModule;