sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ octane/ source.ts

import * as NodeCrypto from "node:crypto";
import * as NodePath from "node:path";
import { fileURLToPath } from "node:url";
/**
 * `@alchemy.run/frontend-frameworks/octane/source` — alchemy Worker source provider for
 * OctaneJS projects.
 *
 * The default export satisfies alchemy's `WorkerSourceModule` contract
 * (`packages/cloudflare/src/Workers/Source.ts`) **structurally**:
 * the `Source*` shapes below mirror alchemy's `SourceProvider` /
 * `SourceContext` / `SourceBuildOutput` interfaces rather than importing
 * them, so this package carries no dependency on alchemy. Version skew
 * degrades to a load-time `SourceProviderError` on the alchemy side.
 *
 * Semantics mirror alchemy's built-in vite source
 * (`Workers/Sources/Vite.ts`):
 *
 * - `build()` runs the Octane Framework service (the project's own
 *   Vite plugins compile the client and server; Alchemy generates the
 *   `dist/server/worker.js` entry without requiring a hosting adapter) and
 *   maps its `BuildOutput` onto the source contract: `serverModules`
 *   (entry first) → bundle files, `clientDirectory` (`dist/client`) →
 *   assets (manifest-hashed, honoring `.assetsignore` / `_headers` /
 *   `_redirects`), project-tree hash → the `input` hash slot.
 * - `hash()` recomputes the `input` hash **without building** — a memo hash
 *   over the project tree (gitignore-aware by default, narrowable via
 *   `memo.include`/`memo.exclude`), the lockfile, this package's version,
 *   and the build-affecting options.
 * - `dev()` starts Octane's own Vite dev server (the plugin's dev SSR
 *   middleware — rendering, server routes, and RPC run in-process with full
 *   HMR) and returns the server-mode dev handle. NOTE: Octane's dev
 *   middleware supplies no request-scoped platform bindings
 *   (`context.platform` is `undefined` in dev — an upstream limitation), so
 *   Worker bindings are not observable from dev-mode app code yet.
 */
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import type * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import type * as Scope from "effect/Scope";
import { glob } from "tinyglobby";
import { resolveBuildEnv, runBuildChild } from "../core/BuildChild.ts";
import { makeCloudflareTarget } from "./cloudflare.ts";
import { make as makeOctane, type OctaneOptions } from "./Octane.ts";

const PROVIDER = "@alchemy.run/frontend-frameworks/octane/source";

// ─────────────────────────────────────────────────────────────────────
// Structural mirror of alchemy's Worker source contract
// (packages/cloudflare/src/Workers/Source.ts). Do not import
// alchemy here — the contract is structural by design.
// ─────────────────────────────────────────────────────────────────────

/** Mirror of alchemy's `SourceHash`. */
export interface SourceHash {
  readonly bundle: string | undefined;
  readonly assets: string | undefined;
  readonly input: string | undefined;
  readonly additionalWorkspaces: Array<string> | undefined;
}

/** Mirror of alchemy's `Bundle.BundleFile` / `Bundle.BundleOutput`. */
export interface SourceBundleFile {
  readonly path: string;
  readonly content: string | Uint8Array;
  readonly hash: string;
}

export interface SourceBundleOutput {
  readonly files: [SourceBundleFile, ...Array<SourceBundleFile>];
  readonly hash: string;
}

/** Mirror of alchemy's `AssetReadResult` (`Workers/Assets.ts`). */
export interface SourceAssetReadResult {
  directory: string;
  config: Record<string, unknown> | undefined;
  manifest: Record<string, { hash: string; size: number }>;
  _headers: string | undefined;
  _redirects: string | undefined;
  hash: string;
}

/** Mirror of alchemy's `SourceBuildOutput`. */
export interface SourceBuildOutput {
  readonly bundle: SourceBundleOutput | undefined;
  readonly assets: SourceAssetReadResult | undefined;
  readonly hash: SourceHash;
}

/** Mirror of alchemy's `SourceContext` (the subset this source reads). */
export interface SourceContext {
  readonly id: string;
  readonly workerName: string;
  readonly compatibility: {
    readonly date: string;
    readonly flags: Array<string>;
  };
  readonly stack: { readonly name: string; readonly stage: string };
  readonly env: Record<string, unknown> | undefined;
  readonly assets: Record<string, unknown> | string | undefined;
}

/** Mirror of alchemy's `DevContext` (the subset this source reads). */
export interface SourceDevContext extends SourceContext {
  /**
   * Runtime wiring derived by alchemy's LocalWorkerProvider. Octane's dev
   * server cannot serve platform bindings yet (see the module doc), so the
   * worker wiring is currently unused — carried for contract parity.
   */
  readonly worker: {
    readonly name: string;
    readonly bindings: ReadonlyArray<unknown>;
  };
  /** The host's pre-built `Context<RuntimeServices>` (opaque here; unused). */
  readonly runtimeContext: unknown;
}

/** Mirror of alchemy's server-mode `SourceDevHandle`. */
export interface SourceDevHandle {
  readonly mode: "server";
  readonly url: URL;
  readonly serviceBinding?: "http";
}

/**
 * Same tag as alchemy's `Cloudflare.Workers.SourceProviderError`, so the
 * errors this module raises are members of alchemy's closed `SourceError`
 * union structurally.
 */
export class SourceProviderError extends Data.TaggedError(
  "Cloudflare.Workers.SourceProviderError",
)<{
  readonly provider: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type SourceError = SourceProviderError | PlatformError;

type SourceServices = FileSystem.FileSystem | Path.Path;

/** Mirror of alchemy's `SourceProvider` (structural). */
export interface SourceProvider {
  readonly ownsAssets: boolean;
  readonly build: (
    ctx: SourceContext,
  ) => Effect.Effect<SourceBuildOutput, SourceError, SourceServices>;
  readonly hash: (
    ctx: SourceContext,
    previous: SourceHash | undefined,
  ) => Effect.Effect<Partial<SourceHash>, SourceError, SourceServices>;
  readonly dev: (
    ctx: SourceDevContext,
  ) => Effect.Effect<SourceDevHandle, SourceError, SourceServices | Scope.Scope>;
}

// ─────────────────────────────────────────────────────────────────────
// Descriptor options (JSON-serializable — they persist in alchemy state
// and participate in the Worker's metadata hash)
// ─────────────────────────────────────────────────────────────────────

export interface OctaneMemoOptions {
  /** Glob patterns of files to hash, relative to `rootDir`. @default all non-gitignored files */
  readonly include?: Array<string> | undefined;
  /** Glob patterns to exclude. @default gitignore rules from `rootDir` up to the repo root */
  readonly exclude?: Array<string> | undefined;
  /**
   * Include the nearest package-manager lockfile in the hash.
   * @default true when both `include` and `exclude` are unset
   */
  readonly lockfile?: boolean | undefined;
}

export interface OctaneSourceOptions {
  /**
   * Octane project root (the directory containing `vite.config.ts` and
   * `octane.config.ts`). Relative paths resolve from the process working
   * directory. @default process.cwd()
   */
  readonly rootDir?: string | undefined;
  /** Narrows the rebuild-detection input hash. */
  readonly memo?: OctaneMemoOptions | undefined;
}

// ─────────────────────────────────────────────────────────────────────
// Hashing (mirrors alchemy's Command/Memo.ts + Util/sha256.ts semantics:
// machine-independent — only relative paths and file bytes are hashed)
// ─────────────────────────────────────────────────────────────────────

const sha256Hex = (input: string | Uint8Array): Effect.Effect<string> =>
  Effect.sync(() => NodeCrypto.createHash("sha256").update(input).digest("hex"));

/** Recursively sort object keys so JSON.stringify is order-stable. */
const stableValue = (value: unknown): unknown => {
  if (Array.isArray(value)) {
    return value.map(stableValue);
  }
  if (value !== null && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value as Record<string, unknown>)
        .filter(([, v]) => v !== undefined)
        .sort(([a], [b]) => a.localeCompare(b))
        .map(([k, v]) => [k, stableValue(v)]),
    );
  }
  return value;
};

const sha256Stable = (input: unknown): Effect.Effect<string> =>
  sha256Hex(JSON.stringify(stableValue(input) ?? null));

/**
 * Convert gitignore-style rules into glob `ignore` patterns — a copy of
 * alchemy's `Util/gitignore-rules-to-globs.ts` (common cases only).
 */
const gitignoreRulesToGlobs = (rules: ReadonlyArray<string>): Array<string> => {
  const out: Array<string> = [];
  for (const raw of rules) {
    const line = raw.trim();
    if (line.length === 0 || line.startsWith("#") || line.startsWith("!")) {
      continue;
    }
    let rest = line;
    const dirOnly = rest.endsWith("/");
    if (dirOnly) {
      rest = rest.slice(0, -1);
    }
    rest = rest.replace(/\\/g, "/");
    if (rest.length === 0) continue;
    const anchored = rest.startsWith("/");
    if (anchored) {
      rest = rest.slice(1);
    }
    if (rest.length === 0) continue;
    const hasSlash = rest.includes("/");
    if (dirOnly) {
      out.push(anchored || hasSlash ? `${rest}/**` : `**/${rest}/**`);
    } else if (anchored || hasSlash) {
      out.push(rest, `${rest}/**`);
    } else {
      out.push(`**/${rest}`, `**/${rest}/**`);
    }
  }
  return out;
};

const findUp = Effect.fnUntraced(function* (
  fs: FileSystem.FileSystem,
  cwd: string,
  filenames: Array<string>,
) {
  let dir = cwd;
  for (;;) {
    for (const filename of filenames) {
      const file = NodePath.join(dir, filename);
      if (yield* fs.exists(file)) {
        return file;
      }
    }
    const parent = NodePath.dirname(dir);
    if (parent === dir) {
      return undefined;
    }
    dir = parent;
  }
});

/** Collect `.gitignore` rules from `cwd` up to the repo root (parents first). */
const readGitIgnoreRules = (
  fs: FileSystem.FileSystem,
  cwd: string,
): Effect.Effect<Array<string>, PlatformError> =>
  Effect.gen(function* () {
    const rules = yield* fs.readFileString(NodePath.join(cwd, ".gitignore")).pipe(
      Effect.map((file) => file.split("\n")),
      Effect.catchTag("PlatformError", () => Effect.succeed([] as Array<string>)),
    );
    const parent = NodePath.dirname(cwd);
    if (parent === cwd || (yield* fs.exists(NodePath.join(cwd, ".git")))) {
      return rules;
    }
    const parentRules = yield* readGitIgnoreRules(fs, parent);
    return [...parentRules, ...rules];
  });

/**
 * Deterministic content hash of the files in `cwd` matched by `memo` —
 * mirror of alchemy's `hashDirectory` (`Command/Memo.ts`).
 */
const hashDirectory = Effect.fnUntraced(function* (
  cwd: string,
  memo: OctaneMemoOptions | undefined,
) {
  const fs = yield* FileSystem.FileSystem;
  const include = memo?.include ?? ["**/*"];
  const exclude = memo?.exclude ?? [
    "**/.git/**",
    ...gitignoreRulesToGlobs(yield* readGitIgnoreRules(fs, cwd)),
  ];
  const lockfile = memo?.lockfile ?? !(memo?.include || memo?.exclude);
  const [files, lockfilePath] = yield* Effect.all(
    [
      Effect.promise(() =>
        glob(include, {
          cwd,
          ignore: exclude,
          onlyFiles: true,
          expandDirectories: false,
          dot: true,
        }),
      ),
      lockfile
        ? Effect.map(
            findUp(fs, cwd, [
              "bun.lock",
              "bun.lockb",
              "package-lock.json",
              "pnpm-lock.yaml",
              "yarn.lock",
            ]),
            (file) => (file ? NodePath.relative(cwd, file) : undefined),
          )
        : Effect.undefined,
    ],
    { concurrency: "unbounded" },
  );
  if (lockfilePath && !files.includes(lockfilePath)) {
    files.push(lockfilePath);
  }
  const hashes = yield* Effect.forEach(
    files.sort(),
    (file) =>
      fs.readFile(NodePath.join(cwd, file)).pipe(
        Effect.flatMap(sha256Hex),
        Effect.map((hash) => `${file}:${hash}`),
      ),
    { concurrency: 16 },
  );
  return yield* sha256Stable(hashes);
});

/** This package's version — part of the `input` hash so an integration upgrade busts the memo. */
const packageVersion = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem;
  const dir = NodePath.dirname(fileURLToPath(import.meta.url));
  const content = yield* fs.readFileString(NodePath.join(dir, "../../package.json"));
  return (JSON.parse(content) as { version: string }).version;
});

/**
 * The rebuild-free `input` hash: project tree + external workspaces +
 * package version + build-affecting options. Mirrors alchemy's
 * `hashViteInput` semantics (`Workers/Sources/Vite.ts`) — never hashes
 * absolute paths, so relocating an identical tree is a no-op.
 */
const hashOctaneInput = Effect.fnUntraced(function* (
  rootDir: string,
  options: OctaneSourceOptions,
  workspaces: Iterable<string>,
) {
  const version = yield* packageVersion;
  const hashWorkspace = (cwd: string, memo?: OctaneMemoOptions) =>
    hashDirectory(NodePath.resolve(rootDir, cwd), memo).pipe(
      Effect.map((hash) => `${NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd))}:${hash}`),
    );
  const [root, ...workspaceHashes] = yield* Effect.all(
    [hashWorkspace(rootDir, options.memo), ...Array.from(workspaces, (cwd) => hashWorkspace(cwd))],
    { concurrency: "unbounded" },
  );
  const hash = yield* sha256Stable({
    version,
    options: {
      memo: options.memo,
    },
    tree: [root, ...workspaceHashes.sort()],
  });
  return {
    hash,
    workspaces: Array.from(workspaces, (cwd) =>
      NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd)),
    ),
  };
});

// ─────────────────────────────────────────────────────────────────────
// Assets (mirror of alchemy's `readAssets` in `Workers/Assets.ts`:
// manifest of 32-hex content hashes, honoring `.assetsignore`,
// `_headers`, `_redirects`; the overall hash excludes the directory
// path so identical bytes hash identically across machines)
// ─────────────────────────────────────────────────────────────────────

const MAX_ASSET_SIZE = 1024 * 1024 * 25; // 25MB (Cloudflare limit)
const MAX_ASSET_COUNT = 20_000;

const maybeReadString = (fs: FileSystem.FileSystem, file: string) =>
  fs
    .readFileString(file)
    .pipe(
      Effect.catchTag("PlatformError", (error) =>
        error.reason._tag === "NotFound" ? Effect.undefined : Effect.fail(error),
      ),
    );

const readAssetsDirectory = Effect.fnUntraced(function* (
  directory: string,
  config: Record<string, unknown> | undefined,
) {
  const fs = yield* FileSystem.FileSystem;
  const [ignore, _headers, _redirects] = yield* Effect.all([
    maybeReadString(fs, NodePath.join(directory, ".assetsignore")),
    maybeReadString(fs, NodePath.join(directory, "_headers")),
    maybeReadString(fs, NodePath.join(directory, "_redirects")),
  ]);
  const files = yield* Effect.promise(() =>
    glob(["**/*"], {
      cwd: directory,
      ignore: [
        ".assetsignore",
        "_headers",
        "_redirects",
        ...gitignoreRulesToGlobs(ignore?.split("\n") ?? []),
      ],
      onlyFiles: true,
      expandDirectories: false,
      dot: true,
    }),
  );
  if (files.length > MAX_ASSET_COUNT) {
    return yield* new SourceProviderError({
      provider: PROVIDER,
      message: `Too many assets in ${directory} (maximum is ${MAX_ASSET_COUNT}, found ${files.length})`,
    });
  }
  const entries = yield* Effect.forEach(
    files.sort(),
    Effect.fnUntraced(function* (name) {
      const file = NodePath.join(directory, name);
      const content = yield* fs.readFile(file);
      if (content.byteLength > MAX_ASSET_SIZE) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: `Asset ${name} is too large (the maximum size is 25 MB)`,
        });
      }
      const hash = (yield* sha256Hex(content)).slice(0, 32);
      return [`/${name.replaceAll("\\", "/")}`, { hash, size: content.byteLength }] as const;
    }),
    { concurrency: 16 },
  );
  const manifest = Object.fromEntries([...entries].sort((a, b) => a[0].localeCompare(b[0])));
  const hash = yield* sha256Stable({ config, manifest, _headers, _redirects });
  return {
    directory,
    config,
    manifest,
    _headers,
    _redirects,
    hash,
  } satisfies SourceAssetReadResult;
});

// ─────────────────────────────────────────────────────────────────────
// The provider
// ─────────────────────────────────────────────────────────────────────

const wrapFrameworkError = (error: { readonly message: string; readonly cause?: unknown }) =>
  new SourceProviderError({
    provider: PROVIDER,
    message: error.message,
    cause: error.cause ?? error,
  });

const assetsConfig = (assets: SourceContext["assets"]): Record<string, unknown> | undefined => {
  if (assets === undefined || typeof assets === "string") {
    return undefined;
  }
  const { directory: _directory, hash: _hash, ...config } = assets;
  return Object.keys(config).length > 0 ? config : undefined;
};

/**
 * The production build runs in a disposable child process with
 * `cwd = project root` (see `core/BuildChild.ts`): the natively-loaded
 * `vite.config.*` executes user plugins that may read the cwd, mutate
 * `process.env`, or `process.chdir` — none of which may touch the engine
 * process. The shared `core/BuildChildRunner`
 * entry imports this module in the child and calls the exported
 * {@link buildInChild}.
 */
export interface OctaneBuildChildConfig {
  readonly rootDir: string;
  readonly compatibilityDate: string;
  readonly compatibilityFlags: Array<string>;
}

export const buildInChild = (config: OctaneBuildChildConfig) =>
  Effect.gen(function* () {
    const framework = yield* makeOctane({
      root: config.rootDir,
      target: makeCloudflareTarget,
      compatibilityDate: config.compatibilityDate,
      compatibilityFlags: config.compatibilityFlags,
    });
    return yield* framework.build({ root: config.rootDir });
  });

export const makeOctaneSource = (options: OctaneSourceOptions): SourceProvider => {
  const rootDir = NodePath.resolve(options.rootDir ?? process.cwd());
  const frameworkOptions = (ctx: SourceContext): OctaneOptions => ({
    root: rootDir,
    // This module is Cloudflare-specific by contract (it implements alchemy's
    // Cloudflare Worker source), so it passes the target factory directly
    // instead of relying on specifier resolution from the project's
    // node_modules.
    target: makeCloudflareTarget,
    compatibilityDate: ctx.compatibility.date,
    compatibilityFlags: ctx.compatibility.flags,
  });
  return {
    ownsAssets: true,
    build: Effect.fnUntraced(function* (ctx) {
      const output = yield* runBuildChild({
        module: import.meta.url,
        rootDir,
        framework: "octane",
        env: resolveBuildEnv(ctx.env),
        config: {
          rootDir,
          compatibilityDate: ctx.compatibility.date,
          compatibilityFlags: ctx.compatibility.flags,
        } satisfies OctaneBuildChildConfig,
      }).pipe(Effect.mapError(wrapFrameworkError));
      if (output.serverModules === undefined || output.serverModules.length === 0) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: "The Octane build produced no server modules",
        });
      }
      if (output.clientDirectory === undefined) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: "The Octane build produced no client directory",
        });
      }
      const files = output.serverModules.map((module): SourceBundleFile => ({
        path: module.name,
        content: module.content,
        hash: module.hash,
      })) as [SourceBundleFile, ...Array<SourceBundleFile>];
      const [bundleHash, assets, input] = yield* Effect.all(
        [
          sha256Stable(files.map((file) => `${file.path}:${file.hash}`)),
          readAssetsDirectory(
            NodePath.resolve(rootDir, output.clientDirectory),
            assetsConfig(ctx.assets),
          ),
          hashOctaneInput(rootDir, options, output.externalWorkspaces),
        ],
        { concurrency: "unbounded" },
      );
      return {
        bundle: { files, hash: bundleHash },
        assets,
        hash: {
          bundle: bundleHash,
          assets: assets.hash,
          input: input.hash,
          additionalWorkspaces: input.workspaces,
        },
      } satisfies SourceBuildOutput;
    }),
    hash: Effect.fnUntraced(function* (_ctx, previous) {
      const { hash, workspaces } = yield* hashOctaneInput(
        rootDir,
        options,
        previous?.additionalWorkspaces ?? [],
      );
      return { input: hash, additionalWorkspaces: workspaces };
    }),
    dev: Effect.fnUntraced(function* (ctx: SourceDevContext) {
      // Octane's dev server serves SSR/HMR in-process but supplies no
      // request-scoped platform (see the module doc) — the worker's binding
      // hooks (`ctx.worker.bindings`) cannot be served into dev app code yet.
      const framework = yield* makeOctane(frameworkOptions(ctx));
      const server = yield* framework
        .dev({ root: rootDir, port: 0 })
        .pipe(Effect.mapError(wrapFrameworkError));
      return {
        mode: "server",
        url: new URL(server.url),
        serviceBinding: "http",
      } satisfies SourceDevHandle;
    }),
  };
};

/**
 * The `WorkerSourceModule` contract: alchemy dynamically imports this module
 * and calls `make(descriptor.options)`.
 */
const sourceModule = {
  make: (options: unknown): Effect.Effect<SourceProvider, SourceProviderError> =>
    Effect.succeed(makeOctaneSource((options ?? {}) as OctaneSourceOptions)),
};

export default sourceModule;